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Abstract 


This redbook describes how to work with LotusScript, a BASIC-like, 
object-oriented programming language that comes as part of Lotus Notes 
Release 4 and other Lotus products. 

The introductory chapter compares LotusScript and Visual Basic. Other 
chapters cover Lotus Notes as an OLE 2 automation server and OLE 2 
automation client. A description of fhe LofusScript Nofes classes is also 
provided. 

The redbook focuses on how to convert HiTest applications, and how to 
access the major Notes elements using: 

• The HiTest Basic API 

• Notes classes in Visual Basic through OLE automation 

• LotusScript in Notes. 

This redbook was written for Visual Basic programmers who want to learn 
about the features of LofusScript, and who are planning to migrate their 
HiTest applications. 

Some knowledge of fhe HiTesf Basic API and of Visual Basic is assumed. 
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Preface 


This redbook describes how to work with LotusScript, a BASIC-like, 
object-oriented programming language that comes as part of Lotus Notes 
Release 4 and other Lotus products. 

The introductory chapter compares LotusScript and Visual Basic. Other 
chapters cover Lotus Notes as an OLE 2 automation server and OLE 2 
automation client. A description of fhe LofusScript Nofes classes is also 
provided. 

The redbook focuses on how to convert HiTest applications, and how to 
access the major Notes elements using: 

• The HiTest Basic API 

• Notes classes in Visual Basic through OLE automation 

• LotusScript in Notes. 

This redbook was written for Visual Basic programmers who want to learn 
about the features of LofusScript, and who are planning to migrate their 
HiTest applications. 

Some knowledge of fhe HiTesf Basic API and of Visual Basic is assumed. 

Note This redbook is available in HTML formal and in Adobe Acrobaf 
formal on the World Wide Web. The URL is 

http://www.lotus.com/devtools. Also, the code samples provided 
throughout the book are available for your use on 
htfp://www.lofus.com/redbook. 


How This Redbook Is Organized 

This redbook is organized as follows: 

• Chapter 1, "LotusScript and Visual Basic: A Comparison" 

This chapter describes the differences and similarities between Visual 
Basic Release 4 and LotusScript. 

• Chapter 2, "The Notes Integrated Development Environment" 

This chapter looks at the Integrated Development Environment (IDE) 
for creafing and programming Nofes forms, which is fhe mosf complex 
applicafion development environment. 
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Chapter 3, "LotusScript Notes Classes" 

This chapter discusses the LotusScript database classes and Ul classes, 
how to access the classes, and the properties and methods of the 
classes. 

Chapter 4, "Lotus Notes as an OLE 2 Automation Server" 

This chapter describes how to develop Notes applications in Visual 
Basic using the Notes classes. 

Chapter 5, "Converting HiTest Applications" 

This chapter describes how to convert HiTest applications using the 
original HiTest code directly in Notes Release 4, using Notes classes in 
Visual Basic through OLE automation, and using LotusScript in Notes. 

Chapter 6, "Accessing Notes Sessions" 

This chapter discusses how to access Notes sessions in HiTest, using 
Notes classes through OLE automation in Visual Basic, and using 
LotusScript in Notes. 

Chapter 7, "Accessing Notes Databases" 

This chapter discusses how to access Notes databases in HiTest, using 
Notes classes through OLE automation in Visual Basic, and using 
LotusScript in Notes. 

Chapter 8, "Accessing Notes Views" 

This chapter discusses how to access Notes views and folders in HiTesf, 
using Nofes classes through OLE automation in Visual Basic, and using 
LotusScript in Notes. 

Chapter 9, "Accessing Notes Documents" 

This chapter discusses how to access Notes documents in HiTest, using 
Notes classes through OLE automation in Visual Basic, and using 
LotusScript in Notes. 

Chapter 10, "Accessing Notes Items" 

This chapter discusses how to access Notes items in HiTest, using 
Notes classes through OLE automation in Visual Basic, and using 
LotusScript in Notes. 

Chapter 11, "Using Notes as an OLE 2 Automation Client: Creating 
Objects" 

This chapter describes how to create embedded and linked objects in a 
Notes document manually and using LotusScript. 



• Chapter 12, "Using Notes as an OLE 2 Automation Client: Managing 
Objects" 

This chapter describes how to edit and update an embedded or linked 
object in a Notes document both manually and using LotusScript. 

• Appendix A, "HiTest and LotusScript Notes Classes: Comparing 
Functions" 

This appendix lists equivalent functions in HiTest and LotusScript. 
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Comments Welcome 


We want our redbooks to be as helpful as possible. Should you have any 
comments about this or other redbooks, please send us a note at the 
following address: redbook@vnef.ibm.com. 

Your comments are important to us! 



Chapter 1 

LotusScript and Visual Basic: A Comparison 


This chapter describes the differences and similarifies befween Visual Basic 
Release 4 and LofusScripf, which comes as parf of Lofus Nofes Release 4 
and ofher Lofus producfs, such as Word Pro, Freelance, and Approach. We 
will compare fhe synfacfical language porfions of LofusScripf and Visual 
Basic. We will also look af fhe environmenfs fhaf fhese languages work 
wifhin. Visual Basic relies on fhe Visual Basic design environmenf, access fo 
exfernal confrols and hosf applicafions such as Excel. LofusScripf relies on 
Nofes, Word Pro and ofher Lofus producfs fo provide fhe user inferface if 
needs fo operafe wifhin. 

So, while fhe primary focus will be on fhe synfax, we will offen explain fhe 
advanfages gained by using fhese exfernal fools wifh bofh LofusScripf and 
Visual Basic. 

Some of fhe fopics covered are: 

• A synfacfical language comparison 

• The programming model of each language 

• The Objecf-Orienfed developmenf characferisfics of each 

• Exfernal objecfs; such as servers, confrols, componenfs fhaf add fo fhe 
language. 


History 

Microsoff released Visual Basic in 1989, buf fhe language has acfually been 
in use since fhe 1960s. In facf, fhere are now many versions of BASIC 
available, wifh implemenfafions found in fools such as PowerBuilder, 
ToolBook, Visual Basic and Lofus Nofes Release 4. 

Prior fo Release 4 of Nofes, Lofus applicafions used a macro command 
language as fhe mefhod of developmenf. While fhis macro language is fairly 
robusf in power, professional developers have come fo prefer a more 
powerful developmenf language. 
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LotusScript 

With Lotus Notes Release 4 and other Lotus desktop applications in 
SmartSuite, Lotus has added LotusScript as a version of BASIC that can be 
used to extend the functionality of fhe applicafions and to integrate with 
other software. This is actually Release 3 of LofusScript. Lofus had released 
LofusScript Release 1 in Improv, with Release 2 appearing in Lotus Forms 
and Notes ViP, an earlier development tool created to interoperate with 
Notes. (Notes ViP is now developed and marketed exclusively by 
Revelation Technologies, Inc. as Revelation ViP for Lofus Nofes.) The ViP 
version of BASIC was fhe firsf fo truly implement Object-Oriented 
Programming (OOP) features, much of which has been carried forward into 
the current version of LofusScript. The implementation of LofusScript 
within Lotus Notes delivers an impressive combination of workgroup 
capabilities, programming environment and the standard reporting and 
database features necessary for applicafion development. This chapter will 
use Lotus Notes to describe user interface feafures and LofusScript in the 
comparison to Visual Basic. 

Visual Basic 

There are three versions of Visual Basic: VBScript, VBA and VB. VBScript is 
the object-enabling language that is used within Web browsing tools to 
allow objects to be loaded, change their properties and react to changes 
(events) within the objects. VBA is a superset of VBScript, providing 
interaction with Microsoft's application tools. Visual Basic is a full 
development tool that provides reporting, database interoperation and 
screen design. 


Programming Model Differences 

There are some differences in the general flow of using LofusScript when 
compared to Visual Basic. Some of fhe more salient points are: 

• Interface Tools Used 

Visual Basic (fhe package) supplies fhe ability to create user interface 
elements, like forms and dialog boxes. LofusScript depends upon Notes 
or the containing Lotus application to provide the actual user interface. 

Visual Basic allows you fo creafe run time, royalty-free applicafions. 
These applicafions are disfribufed as pseudo-compiled modules and 
interprefed before being executed, at run time. LotusScript currently 
works within Lotus Notes and Smart Suite and is distributed to users of 
fhose applicafions. Nofe fhaf LofusScript "scripts" are in fact compiled. 
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Object-Oriented Terminology 

LotusScript uses the term "class" to describe the "contract" defining the 
properties, methods and potentially the events related to an object. 
Microsoft uses the term object in this case and uses Class to describe 
underlying low-level language constructs. LotusScript has the term 
Inheritance in its vocabulary — Visual Basic does not. 

Screen flow 

Nofes screens flow in a manner similar to a script-enabled help file, 
within one form replacing several windows of a traditional, 
dialog-based application. A good deal of information (potentially 
screens' worth) is often placed onto one form in Nofes. This differs 
from the one main screen with supporting dialogs approach used by 
Visual Basic. 

One major reason for the single-screen approach is that a large amount 
of informafion can be placed onto the screen and then "scrolled" or 
graphically navigated to, as opposed to the more traditional dialog-box 
presentation of fhe dafa. A second major reason is fhaf fhe dafa is fhen 
relafively flexible when presented into different screen resolutions or 
even different operating system environments. 

Presentation actually becomes more an issue of sfyle and user training 
than one way being necessarily better than the other. 

This is something that will take a little getting used to from the design 
side as well as the eventual usage of your applicafion. 

Control Placement 

When designing your screens in Notes, you will place controls in 
positions relative to other controls or text on the screen. Rather than 
worrying about finite twip or pixel level placement, you will just put a 
button to the right of fhe prior button or to the left of fhe butfon that 
comes next. Notes handles the final placement of fhe control, to resolve 
potential cross-platform resolution dependencies fhaf occur when you 
specify fhe coordinate system within your application itself. If you 
really want to decide where things sit on the screen, you can add spaces 
or tabs between fields and controls to change the presentation of fhe 
controls. 

OLE 2 Support 

Notes will allow you to place OLE 2.0 controls on the screen. As of 
Nofes Release 4.1, Nofes is a full OCX container. Eor example, events 
are not handled in exactly the same way and it is more difficult to 
change the properties of exisfing controls. Lotus is working on a 
Component Software Development Kit (SDK) to enable OLE control 
developers to create controls within Notes. This SDK will also allow 


Chapter 1: LotusScript and Visual Basic: A Comparison 3 



you to react to events generated within these controls, in the same way 
as other OLE2 containers do now. 

• Structure 

With Release 4 of Lotus Notes, both LotusScript and VisualBasic 
operate within the same type of development environments. Each has a 
layer to present and retrieve information to the user and an underlying 
layer to store this information. 


[Lofiss3ii^ [Hoisfis 

Presentation Layer 
Scripting Layer 
Data Access Layer 


Notes, WordPro 

VB Forms, Excel 

LotusScript 

Visual Basic 

Notes Databases, ODBC 

Access, ODBC 


With Release 4 of Nofes, Lofus has added the LotusScript programming 
layer to bind together the Lotus applications packages as well as to 
increase the ability to use other packages with Notes as well, via OLE 
Automation. 


Language Syntax Comparison 

This section contains a comparison of fhe sfatements and functions making 
up LofusScript and Visual Basic. 

Other References 

This secfion covers fhe low-level syntactical language differences between 
LofusScript and Visual Basic. Much of fhe material in this section will be 
covered at a level just high enough to explain the basic concepts involved. If 
you wish to read more about the language specifics, see fhe LotusScript 
Language Reference (also available within the Notes Help database) and the 
LotusScript Programmer's Guide. The LotusScript manuals are available as a 
documentation pack from Lofus: fhey are nof packaged inside Nofes boxes. 
See the Visual Basic 4.0 Language Reference for more on the Visual Basic 
language. 

The respective web sites of Lofus (http://www.lotus.com/devtools) and 
Microsoft (http:/ /www.microsoft.com) will offer the most up-to-date 
material and announcements about each language and their supporting 
tools. 
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There are many good examples of how to extend the use of LofusScript by 
adding LofusScript Notes classes found in the Notes Programmer's Guide, 
Part 1 - Chapter 4. 

Data Types 

The data t 5 ^es supported under LotusScript and Visual Basic are very 
similar. 

Typeless or Typed variables 

Declaring the t 5 ^e of dafa fhaf a variable holds is nof sfricfly a requirement 
in the typeless, variant data type declarations possible in both LotusScript 
and Visual Basic. While you are able to specify whaf type of dafa a variable 
holds, in bofh languages you can also reserve a 16-byfe piece of sforage by 
simply using the variable without a type. You then assign the "type" of dafa 
for this variable whenever you first load actual data into the variable. For 
example in the first block of code, you'll nofice fhaf UserlD is used without 
first being declared. 

Dim rc ' dim a return code as 

variant 

UserlD = "Bob Sands" ' a variant is created and 'typed' 

' as a string" 

rc = Int(UserlD) ' this will fail at run time since 

' since UserlD is now a string; which 
' is an invalid parm for Int( ). 

whereas the following code will bofh work and will acfually cafch the error 
at design time when compiled, not just at run time: 

Dim rc ' dim a return code as variant 

Dim UserlD# ' a double is created 

UserlD =22.34 

rc = Int(UserlD) ' this will work as expected. 

UserlD = "Bill Sands" ' and this will be caught at design 

' time. 
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Both LotusScript and Visual Basic provide a statement which, when entered 
in the general declarations sections of the code, will force fhe developer to 
explicitly declare the type of dafa of a variable when declared. The 
LofusScript equivalent of Visual Basic's Option Explicit is Option Declare, 
which forces fhe developer to declare all variables before fhey are used. 


Data Type 

LS 

VB 

Suffix 

Storage Size 

Range 

Notes 

Byte 


X 

none 

1 byte 

0 to 255 


Integer 

X 

X 

% 

2 bytes 

-32,768 to 37,767 


Long (long integer) 

X 

X 

& 

4 bytes 

-2,147,483,648 to 
2,147,483,647 

Short integer (2 
byte whole 


number). In 
32-bit Windows, 
VB4 represents an 
int with a 4 byte 
number. 


Single (floating point) X X 


Double (floating X X 

point) 


Currency (scaled X X 

integer) 

String X X 


4 bytes -3.402823E38 to 

-1.401298E-45 or negative 
values; 1.401298E-45 to 
3.402823E38 for positive 
values. 

8 bytes -1.79769313486232E308 to 

-4.94065645841247E-324 for 
negative values; 
4.94065645841247E-324 to 
1.79769313486232E308 for 
positive values. 

8 bytes -922,337,203,685,477.5808 

to 922,337,203,685,477.5807. 


2 bytes per 10 bytes -i- string length 
character* 


0 to 

approximately 2 
billion 

(approximately 
65,400 for 
Microsoft 
Windows version 
3.1 and earlier) 


Variant 

X X 

none 

16 bytes 


user-defined 

X X 

none 

As 

determined 
by its 
elements 


Date 

X 

none 

8 bytes 

January 1,100 to December 

31, 9999 

Boolean 

X 

n/a 

2 bytes 

True or False 
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LotusScript only allows arrays and lists up to 64k in size. Providing a way 
around this restraint should provide a nice after-market for Lofus add-in 
component builders. 

Visual Basic and LotusScript support UNICODE strings. Unicode allow you 
to handle complex languages such as Japanese and Chinese using DECS 
(double-byte, or more, character set) encoding. These languages require 
more than one byte of storage fo represent all possible language characters. 
However, this requires the allocation of an extra byte (or more) of sforage 
for each one desired by fhe programmer. This also requires separafe sefs of 
funcfions fo "see" fhe number of byfes or characters expecfed. 

For example: 

LEN (sfr$) Refurns fhe number of characfers in a sfring, or the number of 
byfes used fo hold a numeric value. 

LENB (sfr$) Determines fhe length of a sfring in byfes rafher than in 
characters. 

The following code demonsfrafes fhe difference in refuming byfe counts or 
character counts for a sfring. Notice fhaf fhe numeric expression refurns 4 
byfes (fhe size allocafed for a single dafa variable) in each case. 

Dim s As Single 

Dim strTemp As String * 20 

strTemp$ = "hello" 

s = 12345 


Msgbox(Format$(Len(s))) ' returns 4 

Msgbox(Format$(Len(strTemp$))) ' returns 20 

Msgbox(Format$(Lenb(s))) ' returns 4 

Msgbox(Format$(Lenb(strTemp$))) ' returns 40 

Defining Defauit Variabies 

Bofh LofusScript and Visual Basic provide a way fo determine default 
ranges for integer and other variable t 3 q)es. For example, saying Deflnt a-z 
in your code will result in single letter variables from a fo z being "typed" 
as integers when used, even if nof explicfly declared with dim x as integer 
or dim x% statements in your code. 

You can set up one-character variables to automatically represent the other 
basic datatypes, thereby avoiding possible portability problems when 
writing your code. For example, DefCur defines Currency variables in the 
same way Deflnt defines Integer variables. 
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DefCur A-D sets the characters A, B, C and D to be typed as currency data 
types automatically. As with Deflnt, subsequent reference to A through D 
will be treated as currency types. Notice that character settings are case 
sensitive; A-Z and a-z represent two possible sets of variables fhat can be 
defined through these DefType statements. 

Collections 

Collections is a Visual Basic Release 4 addition that allows you to set up 
array-like constructs; it can hold multiple types of dafa elements including 
class-based objects that you create yourself. Collecfions is handy in Visual 
Basic and has a number of operations (such as .Add, .Delete, etc.) that can 
be performed direcfly againsf fhe collecfion, but collection processing can 
be somewhat slower than processing against more traditional array 
constructs. 

The Visual Basic Collection keyword is not supported in LotusScript. Using 
the line Dim myUsers as New Collection results in a "Class or 1)^)0 name 
not found: COLLECTION" message. LofusScript handles collecfions as a 
Nofes class. Visual Basic collecfion-based code will need fo be changed fo 
array-based logic when ported to LotusScript. 

Operators 

Both Visual Basic and LotusScript share the same + - / "^ ^\ MOD 
operators, which have the same precedence. The Visual Basic XOR, AND, 
NOT, OR, EQV and IMP operators are also found in LofusScript and 
support bit-wise operations. Both languages provide the Like 
pattern-matching operator for use on sfrings. 


Commands 


LofusScript uses most of fhe same syntacfical sfafements and sfrucfures fhaf 
you will find in Visual Basic. A very short list of LofusScript supported 
statements and functions includes: Fix, FreeFile, GetObject, Hour, InStr, 
IsDate, Kill, LBound, Mid, Option Base, ReDim, Seek and Val. Now even 
returns the system date and time in the same format as Visual Basic. 

Both LotusScript and Visual Basic support multi-line statements, using the 
character to end the line, preceded by white space. 

LotusScript uses the C-like %Rem...%End Rem statements to comment or 
uncomment more than one contiguous line at once. 
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File I/O 

Code such as the following, to open and convert an ASCII text file to UNIX 
format, works exactly the same in both LotusScript and Visual Basic: 

Dim i% 

Dim j% 

Dim strChar$ 

Dim ILOF As Long 
Dim iWinFilePtr% 

Dim iUnixFilePtr% 

' ... skipping the read from input file in here... 

Open strFilename & ".htm" For Output _ 

Access Write As fiUnixFilePtr 
ILOF = LOF(iWinFilePtr%) 

For j% = 1 To ILOF 
strChar$ = Input (1, #iWinFilePtr%) 

If Asc(strChar$) = 13 Then 
Beep 
Else 

Print #iUnixFilePtr%, strChar$; 

End If 
Next j % 

Close iWinFilePtr% 

Close iUnixFilePtr% 

LotusScript and Visual Basic share the ability to Lock and Unlock files 
processed in this way. This ensures that the records you are trying to 
process are not overwritten by others while you are working on them. 

On a binary file, you can lock a record at a time, in an ASCII file, you lock 
and unlock the entire file at the same time. Lock Read, Lock Write, Lock 
Read Write are available in both Visual Basic and LotusScript as parameters 
to the Open statement, to control locking when initially opening a file. 
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other Recent Language Additions 

Recent VBA and VB4 syntactical enhancements have been included in the 
current release of LotusScript. Statements like With and ForAll are found in 
LofusScript. As an example, ForAll allows you fo easily do somefhing to 
every item within a LotusScript collection, such as a list or an integer array: 

dim iSalary(20) as integer 

forall X in iSalary 

X = X * 1.5 ' let's give them a raise they won't forget! 
end forall 

Other interesting statements include Datatype (variable) which returns the 
datatype associated with the object you pass it. Datatype is similar to Visual 
Basic's If TypeOf sfatement, but requires a lot less work. 

Note that the LotusScript End statement is not directly equal to Visual 
Basic's End. The End statement in LotusScript stops the currently executing 
script, and to exit the application in the way you would with Visual Basic's 
End, you generally use the appHalt function. If you are within Lotus Notes, 
you can use the Close macro to easily (and safely) shut the application 
down. 

Error Handling 

LotusScript provides the same t 5 q)e of error handling syntax as Visual Basic 
Release 4, allowing for Err, Erl, Error, Resume, Resume Next, On Error 
Goto label, and so on. 

For example, the following code can be used in bofh LofusScript and Visual 
Basic. 

Sub cmdUpdateDB_Click ( ) 

On Error GoTo cmdUpdateDBErr: 

' process database updates here... 

Exit Sub 
cmdUpdateDBErr: 

' The HandleErr( ) call provides a way to 
' centralize your error processing. The code for 
' the HandleErr call is shown in the 
' object-oriented section below. 

If HandleErr(Err, Error$, _ 
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"frmMain::cmdUpdateDB_Click") then 
resume 
Else 


resume next 
Endlf 


End Sub 

The code for the HandleErr function is broken out and defined for you in 
fhe Objecf-Oriented programming section below. 

On...GoSub 

On...GoSub exists in both variations of Basic as well. On...GoSub allows you 
fo jump (and later return from) different routines using a Select Gase type 
of sfrucfure. All of fhe labels referenced musf reside within the same 
procedure. 

On x% GoSub Labell, Label2, Labels 
Label1: 

' do stuff 
return 


Labels: 

' do stuff 
return 

On...GoTo 
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Conditional Compilation 

Conditional compilation provides a way for developers to code in platform 
or similarly specific sections of code, wifh only fhe code perfaining fo fhe 
runtime plafform acfually being compiled when execufed. The following 
LofusScripf If sfafemenfs, preceded by "%" characfer, are used for 
condifional compilation. 

%if 

%Elself 
%End If 

The above sfafemenfs provide condifional compilation supporf and work in 
fhe same way as fhe #lf ... #End If sfafemenfs do wifhin Visual Basic 4.0. 

You follow fhe %lf or fhe %Elself wifh a consfanf fhaf is provided by fhe 
language or declared explicifly by fhe developer. 

Visual Basic allows you fo define your own consfanfs using a #Consf 
compiler directive. This allows you fo add #lf DEBUGGING type of logic in 
fhe application, providing a way fo compile ouf all debugging code simply 
by removing a #Gonsf DEBUGGING line. 

Ofherwise, bofh LofusScripf and Visual Basic come wifh presef consfanfs fo 
use wifh condifional compilation sfafemenfs. Gode written like fhis shows 
fhe Win32 and OS/2 condifional compilation consfanfs in use: 

%if Win32 

messageBox("Running on Win32") 

%ElseIf 
%If OS/2 

messageBox("Running on OS/2") 

%End If 
%End If 

This will display a message box felling fhe user whaf plafform fhe code is 
running on. The unreachable code is nof execufed af all. 

Lofus recognizes more platforms fhan Microsoff as being legifimafe porfing 
possibilifies. Microsoff supporfs Win32 and Winl6 as consfanfs provided by 
fhe language. In LofusScripf you will find compiler directives for almosf 
everyfhing from SOLARIS fo OS/2. Lofus also adds fhe MAG as a real 
alfemafive fo Win"xx" as well. Using LofusScripf wifhin Nofes provides a 
way fo build fruly cross-plafform, porfable applications. 

The %lf, %End If sfafemenfs are nof provided in Lofus Nofes. 
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MessageBox 

Visual Basic developers will note the MessageBox statement in the 
preceding code. LotusScript defaults to using MessageBox rather than 
MsgBox, although the latter command actually works as well in Lotus 
Notes. Ported MsgBox statements will work, using the parameters specified 
for MessageBox. 

Visual Basic's message box sfafement adds support for two new 
parameters; a helpfile file name and helpcontext id. These are used fo refer 
fo a specific help topic within the named helpfile, if fhe user pushes Fi for 
help over the message box at run time. 

LotusScript allows you to make the MessageBox dialog an application 
modal or system modal dialog. With Visual Basic, it is always an 
application modal dialog. 

Constants 

Both LotusScript (with LTSSL30.LSS and LSCONT.LSS) and Visual Basic 
(W1N16APLTXT and W1N32APLTXT) provide a number of plafform 
specific consfants and Application Programming Interface (API) 
declarafions in a sfandardized formaf. Visual Basic extends this idea by 
bundling a number of fhe consfants into the development environment, 
providing several useful features: 

• Teams do not have to guess at a naming sequence for consfants as they 
add them to their projects. 

• Code becomes easier to share. 

• The space wasted by unused constants is eliminated. 

Examples of fhis include fhe vbHourglass and vbYesNo internal constants. 

Errors, Error Constants 

Both Visual Basic and LotusScript define consfants that map to trappable 
internal error codes, that may occur at run time. Both languages allow you 
to handle system, OLE and data access errors using code-based error 
handling routines at run time. The Basic On Error statement provides the 
means to trap for these errors. Having both languages represent the same 
type of internal errors with the same numbers is an important step in being 
able to share code from one of fhe BASIC implementations to the other. 

As an example, a "Device Unavailable" error occurs if your application tries 
to write to a drive that is not ready. This will happen if you fry to copy files 
fo fhe floppy A: drive without a diskette in this drive. Rather than simply 
displaying a system error message and ending the application. Visual Basic 
and LotusScript treat this as a trappable error, and each gives the developer 
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the chance to deal with it by adding an error handler, if the developer does 
not add the error handler, the application will then display the system error 
message and most likely terminate the application. 

Visual Basic represents the Device Unavailable error with an internal 
number 68. LotusScript also represents this error with the internal number 
68. Most of fhe sysfem-orienfed errors fhaf are frappable errors in Visual 
Basic can be handled by LofusScripf as well, using fhe same numbers. 

LofusScripf provides an ASCII file LSERR.LSS, fhaf defines fhe sysfem 
errors if allows you fo frap. Visual Basic provides a lisf of sysfem. Access 
and OLE errors fhaf if allows you fo frap on as parf of ifs online 
documenfafion. 

There is a general guideline fo how fhe frappable errors are grouped. The 
Visual Basic error groupings are: 

1-94 Sysfem Errors 

260-428 DDE or Eorm Errors 

429-451 OLE Aufomafion Errors 

444-521 Sysfem Errors 

2400-3622 Dafa Access Errors 

4000- Nofes Confainer Errors 

31000-31050 OLE Confainer Errors 

Lofus maps a number of fhe frappable errors for you info consfanfs 
declared in fhe LSERR.LSS file. A snippef of fhe errors defined wifhin fhis 


file are shown in fhe following listing: 

' Run Time LOI Errors 

Public Const ErrFileAlreadyExists = 58 

Public Const ErrBadRecordLength = 59 

Public Const ErrDiskFull = 61 

Public Const ErrInputPastEndOfFile = 62 

Public Const ErrBadRecordNumber = 63 

Public Const ErrBadFileName = 64 

Public Const ErrTooManyFiles = 67 

Public Const ErrDeviceUnavailable = 68 
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Visual Basic provides the ability to Raise an error for an object, which 
allows you to handle the error through external applications or OLE 
servers. The code for fhis looks like fhis: 

object.Raise(Number, Source, Description, HelpFile, HelpContext) 

and works in a similar fashion fo using fhe Error errNumber sfafemenf 
wifhin Basic code. The sysfem believes fhaf fhe error has occurred once you 
issue fhe Error sfafemenf or .Raise mefhod for an objecf, wifh all expecfed 
error fraps enabled as well. 

Nofe fhaf you can generafe your own applicafion-level errors in bofh Visual 
Basic and LofusScripf, by using fhe Error sfafemenf wifh an unused error 
number. For example, if you have an appropriafe On Error Goto trap in a 
section of code, fhe sfafemenf ERROR 147 will generafe a user-defined 
error in bofh languages. 

In Visual Basic you'll receive fhe error sfring "Applicafion-Defined or 
Objecf-Defined Error". In LofusScripf fhe error message generafed would 
be "User-defined error". 

This allows you fo define errors fhaf can be handled fhe same way, sharing 
fhe user-defined error numbers across multiple applications. 


Extending the Code 

Anyone developing complex applications knows fhaf you will need more 
fhan jusf fhe BASIC language synfax ifself, in order fo add complex or 
cusfom processing fo your program. Usually fhis means accessing fhe 
underlying environmenf's API calls, accessing exfernal dafa engines or 
using fhe many cusfom confrols available from fhird-parfy companies. 

Application Programming Interface Calls 

Using API calls allows you fo exfend your programming reach info fhe 
sysfem-orienfed funcfions, available in fhe underlying operafing sysfems. 
Nofe fhaf once you code an API call in a language like LofusScripf or Visual 
Basic, you have added complexify as well as reliance on fhe presence of fhe 
underlying service. LofusScripf and Visual Basic differ on how APIs are 
enabled in fhe respecfive languages. 

32-bit issues 

An example of fhis can again be found in fhe WriteProfileString API call. In 
Windows 3.lx, fhis API call places a sfring info fhe WIN.INI ASCII 
paramefer file. GefProfileSfring can be lafer used fo refrieve fhe sfring. 
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If you move your code to Win32 (Windows 95 or Windows NT) the API call 
no longer works. A new API call GetProfileStringA has been created to 
handle the UNICODE requirements of strings under the 32-bit platform. 

New Visual Basic Statements 

In its most recent release. Visual Basic now supports GetSetting, 

SaveSetting and DeleteSetting commands that provide access to the registry 
on a 32-bit platform (in order to save parameters) and to standard INI files 
on 16-bit platforms. 

Wrapper Examples 

Lotus provides LotusScript wrappers around a number of common APIs, 
such as the Winl6 WriteProfileString, in an .LSS file called LTSSL30.LSS. If 
you desire to use the WriteProfileString, GetProfileInt, GetProfileString API 
calls directly in Visual Basic, you will need to provide wrapper functions 
similar to those provided in the Lotus LTSSL30.LSS file. 


' GetProfString 

' This function returns a profile string from the specified 

' ini file. If the filename passed is then the string 

will 

' be searched for in the WIN.INI file 


Public Function GetProfString(Section as String, Entry as 
String, Filename as String, DString as String) as String 

Dim retstr as String*256 

Dim retval as Integer 

If filename = "" then 

retval = GetProfileString(Section, Entry, DString, 
retstr, 256) 

Else 

retval = GetPrivateProfileString(Section, Entry, DString, 
retstr, 256,Filename) 

End If 

GetProfString = Left$ (retstr, retval) 

End Function 
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Lotus Components 

You can add Windows OCX controls into Lotus Notes today. They will 
visually react when clicked on, but you cannot easily react to events fired 
within the control itself. For example, you will see fhe arrow depress if you 
add a spin buffon fo Nofes and click on fhe arrow. Buf fhere is no easy way 
fo add code fo handle fhis even! when if occurs. 

Lofus Componenfs Soffware Developmenf Kif (SDK) is fhe way Lofus will 
provide fo supporf confrols wifhin Nofes. The SDK enables you fo build 
confrols. 

Automation Servers 

Sub Click (Source As Button) 

Dim session As New NotesSession 

Dim db As NotesDataBase 

Dim doc As NotesDocument 

Set db = session.currentDatabase 

Set doc = New NotesDocument (db) 

doc.Form = "Memo" 

doc.Subject = "Look at the attached code for the " & _ 

"way to mail information within code ..." 

doc.Memo = "This code explains how to use " & _ 

"automation to create a mail 

message." 

Call doc.Send (False, "Shadish") 

End Sub 

Execute Text 

Execute allows you to create a temporary module, at run time, that executes 
and is released when done. Vertical bars I I or | ) are used to allow the text 
to execute to span several lines. 

The Execute doc.txtScript line below pulls script from a text box (txtScript) 
on the form and executes it at runtime. 

Sub Click (Source As Button) 

Print "Starting Script" 

Dim ws As New NotesUIWorkspace 

Dim uidoc As NotesUIDocument 
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Dim doc As NotesDocument 


Set uidoc = ws.CurrentDocument 
Set doc = uidoc.Document 
Execute doc.txtScript 
Print "Completed Script" 

End Sub 


Other Interesting LotusScript Commands 

The Width #filenumber. Width statement forces a set ASCII file width, with 
autowrap to the beginning of fhe next line when the width has been 
exceeded. 

The YIELD statement is equivalent to doEvents in Visual Basic 4. And the 
Yield statement requires a return value, unlike the doEvents in Visual Basic, 
but equivalent to Visual Basic's doEvents function. 

The TypeName (strFiIeName$) statement will return the word "STRING". 
This allows you to determine the datat 5 q)e of a variable af run time, which 
is useful when you have passed variables fhaf may contain any t5q3e of dafa 
in them. 

LotusScript "feels" a litfle more like C++ fhan like BASIC somefimes. 
Beyond the standard BASIC keywords, LotusScript provides for addifional 
syntax such as "Declare"ing a forward reference fo a funcfion or 
subroutine. This allows you to code and test the sub or function before if's 
acfually included in your main app — somefhing that's particularly useful 
in team development environments. Developers familiar with 
Object-Oriented programming will quickly find themselves creating and 
instantiating objects using new (constructors), delete (destructors), and 
data-hiding features you would expect to see in C++. 

On Event Click from <objecf> call <roufine name> allows you to react to 
events happening in other Lotus products. For example, this would allow 
you to create a page-turning presentation to use in a Lotus Notes training 
application. 

Evaluate (Macro, object) allows you to easily call another (Lotus only) 
product macro. This allows you to pass a string of numbers fo a 
spreadsheef fo be fofaled, efc. 

The %lnclude command gives you the ability to include LotusScript 
variable, constant and API declarations into your code from external ASCII 
files. This allows you fo sort through all of fhe various files provided by 


18 LotusScript for Visual Basic Programmers 



Lotus, creating a cut-down version that contains just the statements that 
you need. You can then add all of this to a new application with one line of 
code: %Include "MY-DEFS.LSS". This behaves fhe same as if you were 
using <include mydefs.h> files in C or <include mydefs.hh> files in C++. 
The %Include command can only be used in the general declarations 
sections of an objecf; nof within the event code itself. 

Uni (strExp) and UChr (longValue) fimctions work together like Visual 
Basic's Asc and Char statements, but for Unicode characters. Uni () returns 
the Unicode numeric character code for the first character passed as the 
string parameter. UChr () returns the character represented by the long 
number passed as an argument. 

Using the Print strmgRef command in LotusScript by itself will place the 
string in the last message status bar area of Lofus Nofes, as is shown in this 
figure. 



* * 

Example line of status information! 

'•O None 



This makes for a useful display area when debugging your program and is 
a good place fo drop critical run time messages if you are writing code for 
agents, monitors or other background tasks. 


Other Interesting Visual Basic Commands 

Visual Basic supports Named and Optional parameters in its subs, 
functions and property procedures, allowing you to specify fhe paramefers 
in any order and to choose which parameters you actually want to call the 
routine with. 

Visual Basic allows you to create OLE Servers (EXEs and DLLs in the 32-bit 
version). 


Object-Oriented Programming (OOP) 

Object-oriented (OO) development features include inheritance, 
polymorphism, data encapsulation and creating classes. 

Classes 

A class can be thought of as a template that can be used to create multiple 
instances of objects at run time. Each object contains its own copy of data, 
which can be changed via properties provided externally to the user (or 
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developer). The objects also contain code, which is used to manipulate or 
inspect this data at run time. 

A very simple example might be to create a class to display a message. 
We'll do this in LotusScript by creating a class called DisplayMsg. in the 
following listing, the DisplayMsg class is shown, where you will see a 
property called Text and a method called Display. 

Class DisplayMsg 

' Declare member variables in a LotusScript class 
mMsg As String 
mMsgNumber As Integer 


Public Property Set Text As String 
mMsg = Text 
End Property 


Public Sub Display 
Msgbox(mMsg) 

End Sub 
End Class 

The text for fhe class is enfered info fhe declarafions of a Nofes form. The 
code in fhe nexf listing is enfered info fhe Sub Click even! of a buffon on 
fhis Nofes form. Here you will see a variable creafed as a varianf called 
objMsg, which will be used fo hold fhe insfance of our message objecf. The 
sef objMsg = New DisplayMsg tine acfually creafes fhe insfance of fhe 
objecf and loads a reference of if info fhe objMsg variable. 


Sub Click (Source As Button) 

Dim objMsg as Variant 

Set objMsg = New DisplayMsg 

ObjMsg.Text = "(" & Format$(68) & ") - " & Error$(68) 
objMsg.Display 
Delete objMsg 
End Sub 
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Once you have created the object, you can set the text property by referring 
to it as object.property, or objMsg.Text in this case. You can cause the code 
in the Display method (function) to execute using the same process. 

While this is a simple example, you might easily imagine additional 
possibilities here. The message may actually be "displayed" on a pager, or 
logged to a database, all by adding more code to this basic structure. The 
mechanism to create the object, load its properties and call its methods 
remains the same. 

LotusScript will allow you to use most of fhe mosf important OO 
constructs, like: Building classes. Private and Public data within objects and 
instantiating an object (stored outside your application) from within a 
running application. 

LotusScript also supports single inheritance. LotusScript Notes classes 
support inheritance with the ability to create classes and then subclasses of 
objecfs. Nofe fhaf fhe embedding producf (in this case. Notes) exposes the 
products' functionality as a set of classes. If is fhese "producf classes" fhaf 
can be inherited into your own private classes. 

Visual Basic supports all of fhe objecf-oriented features above, with the 
exception of inheritance. 

Visual Basic Class Modules 

Visual Basic classes are handled through a new "class" of code module, a 
.CLS file. The CLS file is called a Class file. Class files behave like .BAS code 
modules in sfrucfure. The code within the class is used by creating an object 
at run time and then referring to the object's methods and properties. 

Special code is executed when you create an instance of fhe objecf. Similar 
code is execufed when you delefe fhe objecf. Visual Basic classes have a 
Class objecf, which holds Class_lnitialize and Class_Terminafion events. 
Whenever you create a new object, the initialization event is executed. 

When you delete an object, either by leaving the scope where the object was 
created or explicitly by saying Set objRef = Nothing, the termination event 
is executed. 

LotusScript Notes Classes 

Classes within LotusScript are added inline, directly within the code 
modules themselves. Like Visual Basic, LotusScript provides initialization 
and termination procedures within the classes; in this case, called Sub 
Delete and Sub New and Sub Delete. Like Visual Basic, code within these 
procedures is executed automatically. Sub New is executed whenever you 
create an object from the class. Sub Delete is executed whenever you 
destroy the object using the Lotus Delete object statement. 


Chapter 1: LotusScript and Visual Basic: A Comparison 21 



The following example shows how to create and use a LotusScript 

class to create an error handling object. This will demonstrate the use of the 

HandleErr () function in error processing. 

WeTl show the class ErrObject, which will be used to hold and display 
errors. This code was ported from Visual Basic and the comments following 
the class describe the changes that were made to allow the port. 

This is followed by the actual HandleErr function call; that would be called 
by the code in our error-handling discussion earlier. 

Class ErrObject 

Private mErrLogFile As String 

Private mErrNumber As Long 

Private mErrMsg As String 

Private mErrLocation As String 

Private mErrLogMethod As Integer 

Private mErrSeverity As Integer ' change dim to private 

Public Property Get ErrMsg 
ErrMsg = mErrMsg 
End Property 

Public Property Get ErrNumber 
ErrNumber = mErrNumber 
End Property 

Public Property Set ErrNumber ' changed let to set 
mErrNumber = ErrNumber 
End Property 

Public Property Set ErrMessage ' changed let to set 
mErrMsg = ErrMessage 
End Property 
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Public Function PostError(ErrNumber As Variant, 
ErrLocation As Variant, LogMethod As Variant) As Integer 
' pulled the optionals and boolean 
PostError = RESUME_NEXT_AFTER_ERR 

' use object properties if parameters were ommitted. 

If Isempty(ErrNumber) Then ErrNumber = mErrNumber 
If Isempty(ErrLocation) Then ErrLocation = _ 
mErrLocation 

If Isempty(LogMethod) Then LogMethod = mErrLogMethod 

build the message. Note, DB, file output may differ 
slightly, as Date/Time, Err, etc may be written to 
separate columns (fields) 

mErrMsg = Error$(ErrNumber) & " (#" & _ 

Format$(ErrNumber) & ") " & "occurred at " & _ 

Format$(Now, "mm-dd-yy hh:mm:ss") _ 

& at location->" & ErrLocation & 

Select Case LogMethod 
Case LOG_DISPLAY_MESSAGE 
Beep 

Msgbox (mErrMsg) 


Case LOG_TO_DISK 
Dim iLogPtr% 
iLogPtr% = Freefile 

Open mErrLogFile$ For Append Access 
Write As #iLogPtr% 

Print #1, mErrMsg 
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Close #iLogPtr% 


Case LOG_TO_DB 

' not implemnented 
Case LOG_SEND_TO_PAGER 
' not implemented 
Case LOG_SEND_EMAIL 
' not implemented 
Case Else 

Msgbox (mErrMsg) 

End Select 

Select Case ErrNumber 
Case 5 ' invalid procedure call 
ErrSeverity = RECOVERABLE 
PostError = SHUTDOWN_AFTER_ERR 

Case 68 ' device not available (like when user 

' accesses A: without a diskette. Show a 
' message and then resume. 

ErrSeverity = SHUTDOWN_APP 
PostError = RESUME_AFTER_ERR 

Case Else 

ErrSeverity = RECOVERABLE 
PostError = RESUME_NEXT_AFTER_ERR 
End Select 
End Function 
End Class 

In moving the code from Visual Basic to LotusScript, we make the 
following slight modifications. 
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1. Consts move out of the class into the scope of the object the class is in. 

2. Dim statements within the class change to Private. 

3. isMissing is not provided. Replace isMissing with isEmpty. 

4. Optional arguments are not available. Replace Optional with explicit 
variable declarations. 

5. For property functions. Set is used, rather than Let. Set does not have 
the special (but rarely used) object passing features that are present in 
Visual Basic. 

Function HandleErr (iErr%, strErrLocation$, iAction%) As 
Integer 

On Error Goto MetaErr 
Dim objErr 

Set objErr = New ErrObject 

rc = objErr.posterror (iErr%, strErrLocation$, iAction%) 
Delete objErr 
Exit Function 
MetaErr: 

' An error here might come from a failure to create the 
object. 

Msgbox(Format$(Err) & ", " & Error$(Err)) 

Resume Next 
End Function 

The only real change in moving HandleErr from Visual Basic to LotusScript 
is that the object is destroyed explicitly with the Delete objErr statement. 
Notice that the MsgBox call comes across without change. Using HandleErr 
0 results in a message box that looks like this: 
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CreateObject, GetObject 

One advantage for both language dialects is that external OLE servers can 
be added into your applications using these statements. This exposes the 
full power of OLE automation servers, like Word Pro and Notes, to 
applications written in BASIC. 


Mail Enabling 

Eortunately, the ability to create and send e-mail is fairly easy in both 
LotusScript and Visual Basic. 

in LotusScript, to send a message in Notes requires the following type of 
code: 

Sub Click (source as Button)' a button to send info with... 
dim session as new NotesSession 
dim db as NotesDataBase 
dim doc as NotesDocument 
set db = session.currentDatabase 
set doc = new NotesDocument (db) 
doc.Form = "Memo" 
if txtSubject = "" then 

doc.Subject = "Here is a quick thought ..." 

else 

doc.Subject = txtSubject.text 

endif 

if txtMemo = "" then 

doc.Memo = "Example Text" 

else 

doc.Memo = txtMemo.text 

endif 

Call doc.Send (False, "Shadish") 

End Sub 
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In Visual Basic sending a message is equally easy, as a mail control is 
available that embodies much of the mail system's features. The following 
Visual Basic code demonsfrates a MAPI-based mail transfer. If you wish to 
handle cc:Mail or pass through a generic VIM layer, to move mail from a 
Visual Basic sysfem to a VIM-based system, third-party controls are also 
available to do this. After dropping the mail control on your form, enter 
this code behind the send button: 

Sub cmdSend_Click 

frmMain.MapiMess.Action = MESSAGE_COMPOSE 
fritiMain .MapiMess . RecipDisplayName = Address$ 
frmMain.MapiMess.Action = MESSAGE_RESOLVENAME 
if txtSubject = "" then 

frmMain.MapiMess.MsgSubject = _ 

"Here is a quick thought ..." 

else 

frmMain.MapiMess.MsgSubject = txtSubject.text 

endif 

if txtMemo = "" then 

frmMain.MapiMess.MsgNoteText = "Example Text" 

else 

frmMain.MapiMess.MsgNoteText = txtMemo.text 

endif 

frmMain.MapiMess.Action = MESSAGE_SEND 
End Sub 


Code Sharing Concerns 

As far as fhe languages' syntax itself, fhis is nof a major area of concern. 
Much of fhe code writfen for Visual Basic should be able fo move relatively 
easily into LotusScript. 

There are some things that might need to be pointed out. 

Close but Different 

Obviously, the code associated to user interface elements will need to be 
reviewed and most likely rewritten. The way controls are handled in Lotus 
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Notes differs significanfly from Visual Basic. If is easier fo change fhe 
properties of confrols in Visual Basic when compared fo LofusScripf. 
Differenf Windows evenfs are provided for fhe same confrols and fhe 
names of fhese evenfs are also sometimes differenf. 

For example, a button in Visual Basic has fhe following evenfs: 

Click 

DragDrop 

DragOver 

GotFocus 

Keypress 

KeyDown 

KeyUp 

LostFocus 

MouseDown 

MouseMove 

MouseUp 

In addition, you can cause fhe Visual Basic Buffon_Click even! fo execufe 
by setting fhe implied .Value properly of fhe button fo frue, as in 

cmdCancel = True. 

In LofusScripf, fhe evenfs provided for a button are: 

Click 

Terminate 

Initialize 

ObjectExecute 

Options 

Declarations 

Nofice fhe abilify fo include declarations direcfly wifhin an objecf, such as a 
button. 
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Where LotusScript commands and syntax are like Visual Basic's (for 
example, the %lf ... %Endif as compared to the #lf ... #End If conditional 
compilation commands), they will need to be converted, redone or not used 
in order to create code that is truly portable between Visual Basic and 
LotusScript. 

Unlike Visual Basic, LotusScript is not centered around the Properties, 
Methods, and Events metaphor. LotusScript is built around interacting with 
the objects provided within the respective host application and 
development tools provided by Lotus. Eor example, objects don't have Tags 
or Captions. A static text object uses a text property rather than a caption 
property to read and change its value. So any Visual Basic code that refers 
fo capfions for labels needs fo be changed. Similarly, LofusScript doesn't 
support the tag property. But LotusScript does have a Name(variable) 
function that returns an item's name, which can then be used to operate on 
objects dynamically at runtime. 

Control Arrays 

LotusScript does not support control arrays or indexes on individual 
objects in the same way as Visual Basic. So your Visual Basic code that sets 
up an array of fext objecfs with a common code routine — as with Sub 
txtAmtEield_Click (amtldx as index) — will need to be rewritten. Buttons 
under LotusScript are set up as individual buttons or to act as group or 
checkbox buttons when they are placed onto the screen. 

Visual Basic Environment Constants 

If you are using any of fhe new Visual Basic embedded consfants, you will 
need fo provide a translation file of codes for anything that you want to 
move to LotusScript. Or you can simply choose not to use the Visual Basic 
constants in the first place. Eor example, you might be using things like this 
in Visual Basic 4 applications now: 

If rc = vbYes or rc = vbAbort Then 

' add processing here. 

Endlf 

You will need to add constant declarations for vbYes and vbAbort in code 
ported to LotusScript; otherwise the references fo vbYes and vbAbort 
would prove invalid. 

Caution If you are nof using Option Declare in your LofusScript or Option 
Explicit in your Visual Basic modules and move the code shown above, it 
may compile and give you erroneous results. Both vbYEs and vbAbort 
would be treated as uninitialized variables and both contain a 0. The code 
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would execute but give incorrect results since you would always compare 
whatever the contents of rc was to zero. 

Const vbAbort = 3 

Const vbRetry = 4 

Const vbignore = 5 

Const vbYes = 6 

Const vbNo = 7 

Summary 

it's probably safe fo say fhaf a lof of your Visual Basic calculation code will 
port across to LotusScript, but that your interface code will nof move as 
easily. 

LofusScript is enough like Visual Basic's BASIC language implementation 
that you will have few problems porting code from one fool fo fhe ofher — 
if you recognize fhese differences before building any code. With a little 
care, you will be able to easily create routines that can be called from eifher 
Visual Basic or LofusScript without change. 

The problem for the Visual Basic developer writing code to share with 
LotusScript will not be what cannot be moved into LotusScript. Rather, it 
will be in deciding not to use some of fhe appealing LofusScript extensions 
that are now available — like class inheritance, the include% features and 
some of fhe LofusScript Notes classes. 
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Chapter 2 

The Notes Integrated Development Environment 


Introduction 


Lotus Notes provides a complete application development environment. A 
Notes application consists of several or all of fhe following: 

• Forms — which provide fhe femplafes through which data in the 
application is entered and displayed. Unlike a traditional template, 
forms can also acf on the data. For example, when a user inputs 
information in the form, the form might, depending on the contents, 
send an e-mail message to another user. 

• Views and folders — which provide different ways of looking af all or 
part of your dafa, according to specified criteria. A view might be 
thought of as similar to a report in a traditional database program, 
except that the view is dynamic and includes links to information in the 
application. 

• Navigators — which provide graphical means of moving befween 
views. 

• Agents — which add functionality to the application. For example, you 
might create an agent that once a day scans the documents in the 
database, checks the contents of certain fields, and places documents 
that meet specified criteria into a special folder. 

There are, within Notes, Integrated Development Environments (IDESs) for 
developing each of fhe above named elements. These IDEs share many 
common elements. Eor example, the tools for writing LotusScript are 
identical among all of fhe IDEs. We will focus on the forms IDE since if is 
the most complex, and therefore fhe mosf interesting one. Keep in mind, 
though, that much of fhe discussion in this chapter applies to the 
development of all Nofes elements, not just forms. 
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Elements of the Forms Integrated Development Environment 

The picture below illustrates the IDE you use when creating and editing 
forms in Lotus Notes. 



The three components of fhe Infegrafed Developmenf Environmenf are 
represenfed in fhe picfure. 

Main Design Window 

This is fhe large window af fhe fop leff of fhe screen where you visually 
design your form. Using fhis window you can add sfafic fexf, fields, layouf 
regions, and embedded objecfs fo fhe form. 

To work in fhis window you place your cursor af fhe desired position on 
fhe form and type your text, or use the menus or Smartlcons to insert the 
desired object. When you are working in this window the status bar at the 
bottom of the screen provides controls you can use to quickly format text. 
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Action Pane 


This is the narrow window at the top right of the screen. The action pane is 
used to define actions that are associated with the form. An action is a 
LotusScript procedure, simple action, or macro that performs work when 
activated. Actions can be invoked from the menu bar, the action bar, or by 
LotusScript procedures. 

The action pane is not visible in the Integrated Development Environment 
by default. To view the action pane, do one of fhe following: 

1. Choose View —^ Action Pane, or 

2. Drag fhe right-hand edge of fhe main design window to the left, as 
shown in the following figure, imtil fhe action pane is fhe size you 
want. 



To hide the action pane you can either drag its left border all the way to the 
right, choose View —^Action Pane to uncheck the menu option, or click on 
the appropriate Smartlcon. 
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Design Pane 

The design pane is the window below the main design window and the 
action pane. This is where all the programming work in Notes, be it using 
simple actions, the formula language or LotusScript, takes place. 

The design pane is, by default, visible when you create a new form or open 
one for edifing. You can also drag fhe border befween fhe main design 
window and fhe design pane fo change fhe size of bofh, or fo hide fhe 
design pane alfogefher. You can also show and hide fhe design pane by 
choosing View —> Design Pane, jusf as you do fo show and hide fhe action 
pane. 

The design pane is also used when you are creating or edifing a dafabase or 
view acfion. 

There are a number of componenfs fo fhe design pane. Lef's look af each 
one of fhem. 

Define Box 



The define box is a combo box fhaf shows you all of fhe objecfs on your 
form fhaf can be programmed, along wifh all of fhe acfions defined for fhe 
form. 


Event Box 



This combo box shows all of fhe programmable evenfs for fhe objecf 
showing in fhe define box. Each objecf has ifs own sef of evenfs, so fhe 
confenfs of fhis box will change in accordance wifh fhe objecf specified in 
fhe define box. There are also some cases where no evenfs are available, in 
which case fhe evenf box is nof shown. Also, LofusScripf procedures or 
I subs I which you add fo your Nofes applicafion will appear in fhis lisf. 
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Run Area 


L'ciiiic. | vv itluuvv i luc 

Run: C (5 Formula C I” 


The three radio buttons specify the type of programming fhaf you will 
apply fo the specified objecf and evenf. Choose one of fhe following: 

• Simple Acfion(s): Lefs you easily specify one or more acfions from a 
number of pre-defined acfions, such as Modify Field, Send Documenf, 
Move Documenf fo Folder, efc. When you specify Simple Acfion(s), an 
Add Action button (see following figure) appears af fhe bottom of fhe 
design pane. Clicking fhis button brings up a dialog box which allows 
you fo specify fhe action you wish fo perform. Nof all objecfs on fhe 
form supporf simple acfions. If an objecf which does nof supporf simple 
acfions is selecfed in fhe define box, fhis radio buffon is disabled. To 
edif an existing simple action, selecf if wifh fhe mouse and fhen click 
fhe buffon; fhe buffon changes fo Edif Acfion when fhe acfion is 
selecfed. 


Run; Simple aclion(s) P Formula P Script I~ 


Add Action. .. j 

• Formula: Lefs you wrife Nofes formula language macros and 

commands thaf will run when fhe specified evenf occurs for fhe objecf. 
When you specify Formula, a Fields & Functions buffon (see following 
figure) appears af the bottom of fhe design pane. Clicking fhis button 
brings up a dialog box which will display all of the fields defined on fhe 
form, or all of the fxmctions available in the Notes formula language. 
Double-clicking one of fhese fields or functions inserfs it into the editor 
window at the current cursor position. 

Run: O : 9 Formula C f 


Fields ft Funclions... 
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When certain events are selected an ©Commands button will appear 
next to the Fields & Functions button. Clicking this button brings up a 
dialog box which will display all of the ©Commands available in the 
Notes formula language. Nof all objecfs on fhe form supporf formulas. 

If an object which does not support formulas is selecfed in fhe define 
box, this radio button is disabled. 

• Script: Lets you write LotusScript procedures that will rim when the 
specified evenf occurs for the object. When this option is selected, the 
Fields & Functions button and an Error combo box are made available. 
Not all objects on the form supporf LotusScripf. If an objecf which does 
nof supporf LotusScripf is selecfed in fhe define box, fhis radio butfon is 
disabled. 

The lasf confrol in fhe run area is fhe Show Browser check box. This confrol 
is only enabled when the Script radio button is selected. When this control 
is checked, the LotusScript browser is displayed, as shown below: 



The browser is a ready reference of the LotusScript language and functions, 
and of all of fhe objects, their properties and methods. For example, if you 
wanf fo quickly defermine all of fhe mefhods available for fhe 
NotesDocumenf class, show fhe browser and fhen: 

1. Selecf Nofes Classes from fhe fop combo box. All fhe Nofes objecf 
classes are displayed. 

2. Scroll the browser's list box until you find fhe NofesDocumenf enfry. 

3. Click fhe friangular "twisfie" icon fo expand the listing under 
NotesDocument. You will see three entries, for Properfies, Mefhods and 
for Evenfs. The Evenfs enfry has no twisfie, meaning there are no 
events defined for this class. 
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4. Click the Methods twistie, and a list of all of fhe NofesDocument 
mefhods will be lisfed, as shown below: 


Notes: Classes 


▼Notesdocument 

dJ 

► Properties 


Appenditentv3lue(Bjival Argl As Stririr_ 

ComputewithformlArgl As Integer, Arc 
Copiiallitenns(Arg1 As Notesdocument 
CopiiitemlArgl As Notesitem, Byval Ar 
Copytodatabase(Arg1 As Notesdatab< 
CreatereplymessagelBjival Argl As In 


F"'- 1 


5. Double-click the method or property in the browser to insert the 
prototype code into your Notes application. 

Script Editor and Formuia Editor 

The larger window below the rim area is where you program the actions 
that Notes will execute. If fhe Formula radio button is selected, this area is 
the formula editor. If the Script radio button is selected, this area is the 
script editor. 

When the Script button is selected, the script editor will automatically enter 
the appropriate Sub and End Sub statements for the specified objecf and 
event, as the following picfure illusfrafes: 



Error Box 

This box (see figure above) is only displayed when the Script button is 
checked. It lists all of the S 5 mtax errors that Notes detected in your 
LotusScript. If there are multiple errors, clicking the arrow to the right of 
the error box will expand this combo box so that all S 5 mtax errors found are 
displayed. You can navigafe fo a specific error in the list, no matter where 
in the application it is located, by selecting it from the drop-down list. 
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When a syntax error is corrected. Notes will remove the error indication 
from the error box. Notes will not allow you to save a form wifh 
LofusScripf synfax errors, so you will have fo fix all errors (which will 
resulf in an empfy error box) before you will be able fo save your form. If 
you wish fo save an application wifh errors in if, commenf ouf fhe secfions 
fhaf confain errors, or copy fhe confenfs fo fhe clipboard, remove fhe error, 
and save fhe applicafion. 


Working with the Script Editor 

The scripf editor funcfions very much like a fexf edifor. The sfandard fexf 
editor key convenfions are used, such as: 

• HOME places fhe cursor af fhe sfarf of fhe currenf line. 

• END places fhe cursor af fhe end of fhe currenf line. 

• CTRL+HOME places fhe cursor af fhe sfarf of fhe scripf. 

• CTRL+RIGHT ARROW moves fhe cursor one word fo fhe righf. 

You can selecf fexf in fhe usual way (using fhe SHIET and arrow keys, or 
by dragging fhe mouse poinfer over fhe fexf fo be selecfed). The 
clipboard-relafed menus and Smarflcons, such as Cuf and Pasfe, are 
available when you are working in fhe scripf edifor, as well as fhe 
corresponding accelerafor keys, such af CTRL+C and CTRL+V. This means 
fhaf you can cuf and pasfe scripfs, or scripf fragmenfs, from ofher objecfs in 
Notes. 

Speciai Script Editor Features 

One feafure already mentioned was fhe capabilify of looking up LofusScripf 
funcfions and objecfs in fhe browser. If you click on any enfry in fhe 
browser, fhaf enfry becomes highlighfed, and you can click fhe Pasfe buffon 
af fhe bottom of fhe browser fo pasfe fhaf line af fhe currenf cursor posifion 
in fhe scripf edifor. You can also double-click fhe enfry fo copy if fo fhe 
scripf edifor. 

Note In Notes Release 4.5, additional feafures will be available, such as 
colorizafion of idenfifiers, fhe abilify fo exporf or imporf all fhe code, and 
selection of fhe fonf in which fo display fhe scripf. 

Each fime you press fhe ENTER key, or move off a line of LofusScripf, fhe 
scripf edifor checks fhaf line for synfax errors, and also capifalizes fhe 
LofusScripf reserved words, i.e., fhe words in fhe sfafemenf fhaf are a 
componenf of fhe LofusScripf basic language. 
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When you enter structured programming statements such as For, While, 
Do, Select Case, etc., the script editor automatically does the following: 

• Inserts the corresponding ending statement (for example. Loop for fhe 
Do sfafement) below the statement you typed. 

• Inserts a blank line between the two statements, with the cursor being 
placed on that line so you can continue to type your code. 

• Automatically indents the statements within the construct. 

The following figure shows fhe sfate of fhe scripf editor after you type the 
opening statement of a Do loop: 



Define: 

1 Product (Form) _^| Event: | Postopen _^| 

^un: C C Formula Scripf j~ Show browser 


Sub Posfopen(Source As Notesuidocument) 
do while a > Cj 

End Sub 


When the ENTER key is pressed, the script editor window changes as shown 
in the following figure: 




Define: |l Product (Form) 

■^11 Event: | Postopen 

3 


Run: C 

C Formula (•Script P Show browser 


Sub Postopen(Source As Notesuidocument) 

Do While a > 0 


1 

Loop 

End Sub 




LofusScript is nof case sensifive, excepf for text constants. Thus the constant 
"Text" is not the same as the constant "text." It does not matter, then, if you 
sometimes refer fo a variable using upper case, and af ofher fimes use tower 
case; LofusScripf will consider bofh fo refer fo fhe same variable. However, 
if is advisable fhaf you develop a consisfenf naming convenfion and fhen 
sfick fo if. For example, you may have all consfanfs sfarf wifh an upper case 
leffer, and all variables wifh tower case leffers. LofusScripf allows names 
(for consfanfs, variables, efc.) fo have up fo 40 characters, so do nof skimp 
on leffers when naming your variables. Alfhough a variable name such as 
employee_pay_rafe, or employeePayRafe, is harder fo fype fhan p, if is a lof 
more meaningful when you or someone else is frying fo modify fhe code af 
a lafer dafe. By fhe way, long names do not slow down execution of 
LofusScripf because all names are fransformed by fhe compilafion process 
info relafive memory addresses. 
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Error Checking 

There are two types of error checking performed in the script editor: 

1. Each time you move the cursor to a different line, by pressing ENTER, 
using a cursor movement key, or clicking with the mouse. Notes will 
check the syntax of fhaf line in isolation. This kind of syntax check picks 
up errors such as unmatched parentheses and incomplete expressions. 
Notes does not force you to fix these errors right away. You can 
continue entering code. However, Notes will not allow you to save the 
form until the error is corrected. 

2. Whenever you save the form, Nofes will compile fhe LofusScript code, 
and may uncover ofher errors, such as a Selecf Case sfafement with no 
matching End Select statement, and invocations of mefhods which the 
object does not support. When such a compile error is found, Nofes will 
display fhe following message box: 

Script errof(s) found. Choose Yes to edit efror(s); No to continue without saving any changes. 


Yes i| 

No 

--.. ' 



If you click Yes, fhe form is nof saved and you can go and edif fhe code 
to correct the error. If you click No, fhe form is nof saved and any 
changes you made since the last successful save are lost. 

Testing the Form 

Choosing Design —> Tesf Eorm will cause the form to be saved, and a new 
document created based on the form. You can then run this new document 
through its paces to check on how the code you wrote for the form is 
performing. When you complete your testing, press ESC (Notes will ask you 
if you want to save the document) to take you back to the form design IDE. 

Debugging LotusScript 

It is possible that all of your LotusScript statements are syntactically correct, 
and that your program compiles without error, and yet it will not run 
correctly. Consider this very simple code fragment: 

If A + B Then C = 0 

What the programmer meant to t 5 ^e is 

If A = B Then C = 0 

but in haste, the shiet key was not released in typing the equals sign, and 
the plus sign was typed instead. Both statements are syntactically correct. 
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but the results are different. Such errors are called logic errors, meaning 
that the logic of fhe program is flawed. 

For such errors Nofes provides LofusScripf debug facilifies. To invoke fhe 
debugger, choose File —> Tools —> Debug LofusScripf. This menu choice is a 
foggle, so fo fum debugging off, choose fhe same command. 

Note You need fo fum fhe debugger on before loading or creafing fhe 
documenf on which you wanf fhe debugger fo work on. 

When LofusScripf sfarfs execufing, fhe debugger window, shown in fhe 
following figure, will appear: 



Nofice fhe following elemenfs of fhis window: 

• A debug menu on fhe menu bar. 

• Acfion buffons, which confrol fhe execufion of fhe nexf sfafemenf of 
LofusScripf (for defails on fhe operation of each of fhese buffons, 
consulf fhe Nofes documenfafion). 

• Objecf and Evenf combo boxes, which correspond fo fhe Define and 
Evenf combo boxes in fhe form design window. 

• A scripf window fhaf shows fhe currenf scripf sub being debugged. 

• Calls window, which shows fhe sequence of calls fhaf led up fo fhis 
poinf in fhe code. 
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• Information window, where you can see any set breakpoints, the 

current values of variables in your program, and any output produced 
by Print statements in your program. The size of the information 
window and the script window can be changed by dragging their 
common border. 

The statement about to be executed is preceded by a right arrow, and 
highlighted. 


Setting Breakpoints 

Setting breakpoints is useful if you want your program to stop at a specific 
statement, and stepping to the statement is time consuming, or if the 
program only reaches the statement on occasion. In the script window 
select the statement where you want to set the breakpoint, and double click 
it, press F9, or choose Debug —^ Set/Clear Breakpoint. A red stop sign is 
placed to the left of the statement, and an entry is made in the breakpoint 
window in the form objectieventdine. For example, the following figure 
shows we have set a breakpoint at the statement 


set db = session.CurrentDatabase 


iNexi 

Set uidoc = Source 

Set drawing = uidoc.getobiect("Status* *') 

'Get values from View and summarize 
ii Set db = session.CurrentDatabase 

Set view = db.GetView( "1 Products") 

Set doc = view.GetFifstDocument 
Do While Not ( doc Is Nothing) 
phase = 0 

comparedate. Local! ime = doc.P_Launch(0) 

If datenow.TimeDifference(comparedate) < 0 Then phase = 6 
comparedate. Local! ime = doc. PR (0) 

If datenow.!imeDifference(comparedate) < 0 Then phase = 5 
comparedate. Local! ime = doc.!est(0) 


lalls; 5_Proiect_Status; POSTOPEN 


Breakpoints Variables Output 


5_Proiect_Status: Postopen: 17 


The Breakpoints tab of the information window shows us that: 

• The object whose script we are examining is the 5_Project_Status object, 
in this case a form. 

• The event is the Postopen event, which occurs when a document is 
opened. 

• The breakpoint is set at line 17 of this sub. 
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Before we let the code run to the breakpoint, let's look at the Variables tab. 
This is illustrated in the following figure: 


Breakpoints Variables | Output 

UIDOC 

SESSION 

VIEW 

DOC 


DATENOW 
COMPAREDATE 
► PHASE.TEXT 


NOTESUIDOCUMENT 

NOTESUIDOCUMENT 

NOTESSESSION 

NOTESVIEW 

NOTESDOCUMENT 

NOTESDATA0ASE 

NOTESDATETIME 

NOTESDATETIME 

STRING!) 

V^RIAMT 


Note, for example, that variable DB (since LotusScript is case insensitive, db 
and DB are the same variable) is listed, and it is of type NotesDatabase. 
However, at this time there is no value assigned to this variable. If we let 
the script run by clicking the Continue button, we see the following: 


Ob(ec*: 15 Reject Status (Form) ^|| Event: | Postopen 

3 

Next 


Set uidoc » Source 


Set drawirg = uidoc. getobject!"Statu$"| 


'Get values from View and summarize 



Set view = db.GetVtew) '1 Products") 
Set doc = view.GetFirstOocument 
Do While Not f doc Is Nothino 1 


The program has stopped just prior to executing the Set db statement. We 
wish to find out what happens when this statement is executed. We click 
the Step Into button, and the statement is executed, and Notes stops prior 
to executing the next statement. If we now look at the Variables tab in the 
information window we see the following: 


^ UIDOC 
^SESSION 
VIEW 
DOC 

► DG 

► DATENOW 

► COMPAREOATE 

► PHASE.TEXT 


NOTESUIDOCUMENT 

NOTESUIDOCUMENT 

NOTESSESSION 

NOTESVIEW 

NOTESDOCUMENT 

NOTESDATABASE 

NOTESDATETIME 

NOTESDATETIME 

STRING! 1 

VARIANT 


Note that scalar variables, such as 1, display their value. More complex 
variables, such as DB (which, as a result of the statement just executed, 
points to a NotesDocument object) have a twistie to their left. Clicking on 
the twistie displays the components of the variable. Since a NotesDocument 
is composed of fields, clicking on its twistie displays the fields in the 
document and their current values, as shown in the following figure: 


DOC NOTESDOCUMENT 

▼HS NOTESDATABASE 

ISFTINDEXED False VARIANT 

TITLE Product Manager Working STRING 

CATEGORIES VARIANT 

TEMPLATENAME STRING 

DESIGNTEMPLATENAME STRING 

FILENAME PMANAGER working.NSF STRING 

FILEPATH c:Motu$\note$\data\PMANAGER working.NSF STRING 

LASTMODinED e-'20/'96 3:41:38PM VARIANT 


Thus the debugger is a powerful tool in helping you understand what your 
program is doing. 
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Chapter 3 

LotusScript Notes Classes 

Notes defines LotusScript object classes (called Notes classes in the 
following) that allow you to access Notes structures at two levels: 

The database (back-end) classes allow you to access named databases, 
views, documents, and other Notes objects. Both workstation and server 
users can run scripts that access database objects. 

The U1 (front-end) classes allow you to access current objects that the user 
is working on. Only workstation users can run scripts that access U1 objects. 

There is a hierarchical relationship for object classes. Higher hierarchical 
classes contain the lower ones. Each class has defined members, properties 
and methods. Using these members, you can access other objects. The 
relationship of containment and access means that the higher class has 
the property or the method to access the lower one. NotesSession is the 
highest-level class in the hierarchy among the database classes. The 
NotesUlWorkspace class is the highest-level class in the hierarchy among 
the U1 classes. 

In this chapter, we will discuss: 

• Database classes and U1 classes 

• How to access the classes 

• The properties and methods of the classes 
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The following figure shows fhe hierarchy of Nofes classes: 


Front_Eiid 


Back_End 



Note This charf includes fhe 18 classes available wifh Lofus Nofes Release 
4.1. There will be an addifional six classes available wifh Nofes Release 4.5. 
These classes are documenfed in fhe following, and will be idenfified as 
Release 4.5 classes in fhe fexf. 
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The Database (back_end) Classes 

There are 16 database (back-end) classes available in Release 4.1. An 
additional five database classes will be available with Release 4.5. The 
classes are as follows: 


Class 

Description 

NotesACL 

Represents a collection of all the access control list 
entries for a database. 

NotesACLEntry 

Represents a single entry in an access control list. 

NotesAgent 

Represents an agent. 

NotesDatabase 

Represents a Notes database. 

NotesDateTime 

Provides a means to translate between LotusScript 
and Notes date/time formatting. 

NotesDbDirectory 

Represents the database files on a server or the local 
machine. 

NotesDocument 

Represents a document in a database. 

NotesDocumentCollection 

Represents a collection of documents. 

NotesEmbeddedObject 

Represents embedded objects, links, and file 
attachments. 

Notesitem 

Represents a piece of data in a document. 

NotesLog 

Represents actions and errors that occur during a 
script's execution. 

NotesNewsLetter 

A summary document that contains information 
from, or links to, several other documents. 

NotesRichTextItem 

Represents items that can contain rich text. 

NotesSession 

Root of Notes database objects—for global attributes, 
context, and persistent information. 

NotesView 

Represents a named view of a database. 

NotesViewColumn 

Represents a column of a view. 

NotesDateRange 

Represents a range of Notes date. 

NotesForm 

Represents a Notes form. 

Notesinternational 

Represents date-time settings from operating system. 

NotesName 

Represents a name. 

NotesTimer 

Represents a timer. 


Note The classes lisfed in italics will be available in Lofus Nofes Release 

4.5. 
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NotesACL 


Every NotesDatabase contains a NotesACL object representing that 
database's access control list. To get NotesACL, use the ACL property in 
NotesDatabase. NotesACL also contains NotesACLEntry. 

The NotesDatabase class has three methods: Query Access, GrantAccess 
and Revoke Access. You can use these methods to access and modify an 
ACL without declaring a NotesACL object. All you need to know is the 
name of fhe person, server, or group. 


Method 

Description 

AddRole 

Adds a role to an ACL. 

CreateACLEntry 

Creates an entry in the ACL with the name and level that 
you specify. When used with OLE automation, this 
method allows you to create a NotesACLEntry object 
without using the New method. 

DeleteRole 

Deletes a role from an ACL. 

GetEntry 

Given a name, finds its entry in an ACL. 

GetEirstEntry 

Returns the first entry in an ACL, usually the -Default- 
entry. 

GetNextEntry 

Given an ACL entry, returns the next one. 

RenameRole 

Changes the name of a role. 

Save 

Saves the changes you've made to the ACL. If you don't 
call Save before closing a database, the changes you've 
made to the ACL are lost. 


Property Description 

Parent Read-only. The database that owns an ACL. 

Role Read-only. All the roles defined in an access control list. 

UniformAccess Read-Write. Enables the "uniform access" option for the 

database. 

Note The property listed in italics will be available in Lotus Notes Release 

4.5. 

NotesACLEntry 

To create a new NotesACLEntry object, we use the New method of 
NofesACLEnfry or fhe CreafeACLEnfry mefhod of NofesACL. The New 
mefhod creafes an enfry in an ACL wifh fhe name and level fhaf you 
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specify. You must call Save on the ACL if you want the modified ACL to be 
saved to disk. 

NotesACL provides three ways to access an existing NotesACLEntry: 

• To access an entry in an ACL when you know its name, use GetEntry. 

• To access the first entry in the ACL, use GetEirstEntry. 

• To access entries after the first one, use GetNextEntry. 


Method 

Description 

DisableRole 

Given a role, disables the role for an entry. 

EnableRole 

Given the name of a role, enables the role for an 
entry. 

IsRoleEnabled 

Given a role, indicates if the role is enabled for an 
entry. 

New 

Creates a new ACLEntry. 

Remove 

Removes an entry from an access control list. 


Property 

Description 

CanCreateDocuments 

Read-Write. For an entry with Author access to a 
database, indicates if the entry is allowed to create 
new documents. 

CanCreatePersonalAgent 

Read-write. Indicates if an entry can create 
personal agents in a database. 

CanCreatePersonalFolder 

Read-write. Indicates if an entry can create 
personal folders in a database. 

CanDeleteDocuments 

Read-Write. For an entry with Author access or 
above to a database, indicates if an entry can 
delete documents. 

Level 

Read-Write. The access level this entry has for this 
database. 

Name 

Read-Write. The name of an entry. 

Parent 

Read-only. The access control list that contains an 
entry. 

Roles 

Read-only. The roles that are enabled for an entry. 
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NotesAgent 

NotesAgent is contained by NotesSession and NotesDatabase. To access the 
agent that's currently running, use the CurrentAgent property of 
NotesSession. To access all the agents in a database, use the Agents 
property of NofesDafabase. 


Method Description 

Remove Permanently deletes an agent from a database. 

Run Runs an agent from a database. 


Property 

Description 

Comment 

Read-only. The comment that describes an agent, as 
entered by the agent's designer. 

CommonOwner 

Read-only. The name of the person who last modified 
and saved an agent (the agent's owner). If the owner 
has a hierarchical name, only the common name is 
returned. 

IsEnabled 

Read-only. Indicates if an agent is able to run or not. 

IsPublic 

Read-only. Indicates if an agent is public or personal. 

LastRun 

Read-only. The date that an agent last ran. 

Name 

Read-only. The name of an agent. Within a database, 
the name of an agent may not be unique. 

Owner 

Read-only. The name of the person who last modified 
and saved an agent (the agent's owner). If the owner 
has a hierarchical name, the entire name is returned. 

Parent 

Read-only. The database that contains an agent. 

Query 

Read-only. The text of the query used by an agent to 
select documents. 

ServerName 

Read-only. The name of the server on which an agent 
runs. 


Note The method listed in italics will be available in Lotus Notes Release 

4.5. 


50 LotusScript for Visual Basic Programmers 



NotesDatabase 

NotesDatabase is contained by NotesSession and NotesDbDirectory. 

It contains NotesACL, NotesAgent, NotesDocument, 

NotesDocumentCollection, and NotesView. 

Note In Notes Release 4.5, NotesDatabase will contain NotesForm and will 

be contained by NotesUIDatabase. 

We have many ways to access NotesDatabase: 

• To access an existing database when you know its server and file name, 
use the New method of NofesDafabase, or fhe GefDafabase mefhod of 
NofesSession. 

• To access fhe dafabase in which a scripf is currenfly running, wifhouf 
indicafing a server or file name, use fhe CurrenfDafabase properfy of 
NofesSession. 

• To access an exisfing dafabase when you know ifs server and replica 
ID, use fhe OpenByRepIicalD mefhod of NofesDafabase. 

• To access an exisfing dafabase when you know ifs server buf nof ifs file 
name, use fhe NofesDbDirecfory class. 

• To access fhe currenf user's mail dafabase use fhe OpenMail mefhod of 
NofesDafabase. 

• To open fhe defaulf Web Navigator dafabase, use fhe OpenURLDb 
mefhod of NofesDafabase. 

• To access fhe available Address books, use fhe AddressBooks properfy 
of NofesSession. 

• To fesf for fhe exisfence of a dafabase wifh a specific server and file 
name before accessing if, use one of fhese properfies or mefhods of 
NofesDafabase: IsOpen, Open, OpenlfModified. 

• To creafe a new dafabase from an exisfing dafabase, use one of fhese 
mefhods of NofesDafabase: CreafeCopy, CreafeFromTempIafe, 
CreafeRepIica. 

• To creafe a new dafabase from scrafch, use fhe Creafe mefhod of 
NofesDafabase. 

• To access a dafabase when you have a NofesView, NofesDocumenf, 
NofesDocumenfCoIIecfion, NofesACL, or NofesAgenf from fhaf 
dafabase, use fhe appropriate Parenf (or ParenfDafabase) properfy. 
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Method 

Description 

New 

Creates a new NotesDatabase object. 

Close 

Closes a database. 

Compact 

Compacts a database. 

Create 

Creates a new database on disk, using the server 
and file name that you specify. Because the new 
database is not based on a template, it is blank 
and does not contain any forms or views. 

CreateCopy 

Creates an empty copy of the current database. 

The copy contains the design elements of the 
current database, an identical access control list, 
and an identical title. The copy does not contain 
any documents and is not a replica. 

CreateDocument 

Creates a document in a database and returns a 
NotesDocument object that represents the new 
document. You must call Save if you want the 
new document to be saved to disk. When used 
with OLE automation, this method allows you to 
create a NotesDocument object without using the 
New method. 

CreateFromT emplate 

If the current database is a template, creates a new 
database from the template. The new database 
has the design features of the template and does 
not contain any documents. 

CreateReplica 

Creates a replica of the current database at a new 
location. 

FTSearch 

Conducts a full text search of all the documents in 
a database. 

GetAgent 

Gets an agent by agent name in the database. 

GetDocumentBylD 

Finds a document in a database, given the 
document's NotelD. 

GetDocumentByUNID 

Finds a document in a database, given the 
document's universal ID (UNID). 

GetDocumentByURL 

Instantiates a document in the Web Navigator 
database and returns a NotesDocument object for 
it. The database must be an open Web Navigator 
database. 

GetForm 

Gets a form by form name in the database. 

GetProfileDocument 

Gets a profile document of the database. 


Continued 
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Method 

Description 

GetURLHeaderInfo 

Gets the specific Hypertext Transfer Protocol 
(HTTP) header information from the uniform 
resource locator (URL). A URL is a text string 
used for identifying and addressing a Web page. 

GetView 

Finds a view or folder in a database, given the 
name or alias of the view or folder. 

GrantAccess 

Modifies a database access control list to provide 
the specified level of access to a person, group, or 
server. 

Open 

Opens a database. A database must be open in 
order for a script to access its properties and 
methods. 

OpenByReplicalD 

Given a server name and a replica ID, opens the 
specified database, if it exists. 

OpenlfModified 

Given a date, opens the specified database if it has 
been modified since that date. 

OpenMail 

Assigns a database to the current user's mail 
database and opens the database. 

OpenURLDb 

Binds the current database object to the default 
Web Navigator database. If the object is currently 
bound to another database, that database is closed 
first. 

OpenWithFailover 

Finds a replica database on another server if the 
first choice is not available. 

QueryAccess 

Returns a person's, group's, or server's current 
access level to a database. 

Remove 

Permanently deletes a database from disk. 

Replicate 

Replicates a database with its replica(s) on a given 
server. 

RevokeAccess 

Removes a person, group, or server from a 
database access control list. This resets the access 
level for that person, group, or server to the 
Default setting for the database. 

Search 

Given selection criteria for a document, returns all 
documents in a database that meet the criteria. 

UnprocessedFTSearch 

Given selection criteria for a document, returns 
documents in a database that the current agent 
considers to be unprocessed or that match the 
query. 


Continued 
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Method 

Description 

UnprocessedSearch 

Given selection criteria for a document, returns 
documents in a database that the current agent 
considers to be unprocessed, meet the criteria, or 
were created or modified since the cutoff date. 

UpdateFTindex 

Updates the database's full text index. 


Property 

Description 

ACL 

Access control list for the database 

Agents 

Agents in the database 

AllDocuments 

All the documents in the database 

Categories 

(Read-write) Categories in the database 

Created 

Date and time the database was created. 

CurrentAccessLevel 

User's access level to the database 

DelayUpdates 

Read-Write. When doing multiple updates to 
documents on a server, don't do a synchronous 
write for each update; let the server batch them 
later. 

DesignT emplateN ame 

Database's design template, if any 

FileName 

Database file name 

FilePath 

Database path 

Forms 

Notes form array 

IsMultiDbSearch 

Read-Write. True if the database contains a 
multi-database full-text search index. 

IsFTIndexed 

True if the database is full text indexed. 

IsOpen 

True if the database is open. 

IsPrivateAddressBook 

True if the database is a Personal Address Book; 
only valid through AddressBooks in 

NotesSession. 

IsPublicAddressBook 

True if the database is a Public Address Book; 
only valid through AddressBooks in 

NotesSession. 

LastFTIndexed 

Date and time a full text index, if any, was last 
updated. 

LastModified 

Date and time the database was last modified. 


Continued 
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Property 

Managers 

Parent 

PercentUsed 

ReplicalD 

Server 

Size 

SizeQuota 

T emplateN ame 
Title 

UnprocessedDocuments 

Views 


Description 

Users that have Manager access to the database. 
Current Notes session 

Percent of a database's total size that is occupied 
by real data. 

Database replica ID in hexadecimal 
Name of the server containing the database. 
Database size, in bytes 

(Read-write) Database size quota, if any; you 
must be an administrator to write. 

Database template name, if database is a template. 
(Read-write) Database title 

All documents not yet processed in agent or view. 
Named views in the database 


Note The properties and methods listed in italics will be available in Lotus 
Notes Release 4.5. The FTSearch method will change in Release 4.5; two 
new optional arguments, sort and other, will be available. The Close 
method will no longer be available in Release 4.5. 

NotesDateRange 

The NotesDateRange class will be available in Notes Release 4.5. It contains 
NotesDateTime. 

Property Description 

EndDateTime Read-Write. The end time of NotesDateRange. 

StartDateTime Read-Write. The start time of NotesDateRange. 

Text Read-Write. Text format of the date range. 
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NotesDateTime 

NotesDateTime is contained by NotesSession and NotesDateRange. To 
create a new NotesDateTime object, you can use the New method of 
NotesDateTime, or the CreateDateTime method of NofesSession. Given a 
sfring thaf represents the date and time you want. New creates an object 
that represents that date and time. 


Method 

Description 

New 

Creates a new DateTime Object. 

AdjustDay 

Increments a date-time by the number of days 
you specify. 

AdjustHour 

Increments a date-time by the number of hours 
you specify. 

AdjustMinute 

Increments a date-time by the number of minutes 
you specify. 

AdjustMonth 

Increments a date-time by the number of months 
you specify. 

AdjustSecond 

Increments a date-time by the number of seconds 
you specify. 

AdjustYear 

Increments a date-time by the number of years 
you specify. 

ConvertToZone 

Converts the time/date value to the specified time 
zone. 

SetAnyDate 

Sets the date component to a wildcard value, 
which means it will match any date. The time 
component is unaffected. 

SetAnyTime 

Sets the time component to a wildcard value, 
which means it will match any time. The date 
component is unaffected. 

SetNow 

Sets the value of a date-time to now (today's date 
and current time). 

T imeDif ference 

Finds the difference in seconds between one 
date-time and another. 
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Property 

Description 

GMTTime 

Read-only. A string representing a date-time, 
converted to Greenwich Mean Time (timezone 0). 

IsDST 

Read-only. Indicates if the time reflects daylight 
savings time. 

LocalTime 

Read-Write. A string representing a date-time, in 
the local time zone. 

LSGMTTime 

Read-only. A LotusScript variant representing a 
date-time, converted to Greenwich Mean Time 
(timezone 0). 

LSLocalTime 

Read-Write. A LotusScript variant representing a 
date-time, in the local time zone. 

TimeZone 

Read-only. An integer representing the time zone 
of a date-time. In many cases, but not all, this 
integer indicates the number of hours which must 
be added to the time to get Greenwich Mean 

Time. May be positive or negative. 

ZoneTime 

Read-Only. Displays the time/date in the zone in 
which it was originally stored. 


Note The properties and methods listed in italics will be available in 
Lotus Notes Release 4.5. 

N otes D b D i recto ry 

The NotesDbDirectory class is contained by NotesSession and contains 
NotesDatabase. 


You create a new NotesDbDirectory object using the name of the server you 
want to access. You can use the New method of NofesDbDirecfory or the 
GetDbDirectory method of NofesSession. 


Method 

Description 

New 

Creates a new NotesDbDirectory object. 

GetFirstDatabase 

Returns the first database on a server (or local 
computer), using the file type you specify. 

GetNextDatabase 

Returns the next database in a directory, using the 
file type specified in the GetFirstDatabase 
method. 
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Property 

Description 


Name 

Read-only. The name of the server whose 
database directory you are searching. This 
property is set when you create a database 
directory using New. 

Note For GetFirstDatabase, you must use the type number in Visual Basic 
using Notes Classes through OLE Automation, rather than the type 
constant used in LotusScript. 

Type Constant 


Type Number 

DATABASE 


1247 

TEMPLATE 


1248 

REPLICA _CANDIDATE 


1245 

TEMPLATE_CANDIDATE 


1246 


NotesDocument 

NotesDocument is contained by NotesDatabase, NotesDocumentCollection, 
and NotesView. It contains NotesEmbeddedObject, Notesitem, and 
NotesRichTextItem. 

To create a new NotesDocument object, we use the New method of 
NotesDocument or the CreateDocument method of NofesDafabase. 


You musf call Save if you want the new document to be saved to disk. 


Method 

Description 

New 

Creates a new NotesDocument object. 

AppendItemValue 

Creates a new item on a document and sets the 
item's value. 

ComputeWithForm 

Validates a document by executing the default 
value, translation, and validation formulas, if any 
are defined in the document's form. 

Copy Allitems 

Copies all items in a document. 

Copyltem 

Given a destination document, copies all of the 
items in the current document into the destination 
document. The item names are unchanged. 

CopyToDatabase 

Copies a document into the specified database. 

CreateReplyMessage 

Creates a new document that is formatted as a 
reply to the current document. 


Continued 
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Method 

Description 

CreateRichT extitem 

Creates a new rich text item in a document, using 
a name you specify, and returns the 
corresponding NotesRichTextItem object. When 
used with OLE automation, this method allows 
you to create a new rich text item and 
NotesRichTextItem object without using the New 
method. 

Encrypt 

Encrypts a document in a database. 

GetAttachment 

Given the name of a file attachment, returns a 
NotesEmbeddedObject representing the 
attachment. 

GetFirstItem 

Given a name, returns the first item of the 
specified name belonging to the document. 

GetItemValue 

Given the name of an item, returns the value of 
that item in a document. 

GetNextItem 

Given an item, returns the next item of the same 
name belonging to a document. 

Hasitem 

Given the name of an item, indicates if that item 
exists in the document. 

MakeResponses 

Makes one document a response to another 
document. The two documents must be in the 
same database. 

PutinFolder 

Adds a document to the specified folder. If the 
folder does not exist in the document's database, 
it is created. 

Remove 

Permanently deletes a document from a database. 

RemoveFromFolder 

Removes a document from the specified folder. 

Removeltem 

Given the name of an ifem, deletes the item from 
a document. 

RenderT oRTItem 

Creates a picture of a document and places it into 
a rich text item you specify. The picture is created 
using both the document and its form; therefore, 
the form's input translation and validation 
formulas are executed. 

ReplaceltemV alue 

Replaces all items of the specified name with one 
new item, which is assigned the specified value. If 
the document does not contain an item with the 
specified name, the method creates a new item 
and adds it to the document. 


Continued 
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Method Description 

Save Saves any changes you have made to a document. 

Send Mails a document to the recipients you specify. 

Sign Signs a document. 


Property 

Description 

Authors 

Read-only. The names of the people who have 
saved a document. 

ColumnValues 

Read-only. An array of values, each element of 
which corresponds to a column value in the 
document's parent view. 

Created 

Read-only. The date a document was created. 

EmbeddedObjects 

Read-only. The OLE/2 and OLE/I embedded 
objects in a document. 

EncryptionKeys 

Read-Write. The key(s) used to encrypt a 
document. The Encrypt method uses these keys 
when it encrypts the document. 

EncryptOnSend 

Read-Write. Indicates if a document is encrypted 
when mailed. 

ETSearchScore 

Read-only. The full text search score of a 
document, if it was retrieved as part of a full text 
search. 

HasEmbedded 

Read-only. Indicates if a document contains one 
or more embedded objects, object links, or file 
attachments. 

IsNewNote 

Read-only. Indicates if a document is new. A 
document is new if it hasn't been saved. 

IsProfile 

Read-only. Indicates if a document is a profile 
document. 

IsResponse 

Read-only. Indicates if a document is a response 
to another document. 

IsSigned 

Read-only. Indicates if a document contains a 
signature. 

IsUIDocOpen 

Read-only. True if this document was accessed 
from a NotesUIDocument. 

IsUnread 

Read-only. True if this document was unread. 


Continued 
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Property 

Description 

Items 

Read-only. All the items in a document. An item 
is any piece of data stored in a document. 

Key 

Read-only. Profile key, if this is a profile 
document. 

LastAccessed 

Read-only. The date a document was last 
modified or read. 

LastModified 

Read-only. The date a document was last 
modified. 

N ameOfProfile 

Read-only. The name of the profile document, if it 
is a profile document. 

NotelD 

Read-only. The NotelD of a document, which is 
an 8-character combination of letters and numbers 
that uniquely identifies a document within a 
particular database. 

ParentDatabase 

Read-only. The database that contains a 
document. 

ParentDocumentUNID 

Read-only. The universal ID of a document's 
parent, if the document is a response. Returns an 
empty string ("") if a document doesn't have a 
parent. 

ParentView 

Read-only. The view from which a document was 
retrieved, if any. If the document was retrieved 
directly from the database or a document 
collection, returns Nothing. 

Responses 

Read-only. The immediate responses to a 
document. 

SaveMessageOnSend 

Read-Write. Indicates if a document is saved to a 
database when mailed. Only applies to new 
documents that have not yet been saved. 

SentByAgent 

Read-only. Indicates if a document was mailed by 
a script. 

Signer 

Read-only. The name of the person who created 
the signature, if a document is signed. 

SignOnSend 

Read-Write. Indicates if a document is signed 
when mailed. 

Size 

Read-only. The size of a document in bytes, 
which includes the size of any file attachments in 
the document. 


Continued 
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Property 

Description 

UniversallD 

Read-only. The Universal ID of a document, 
which is a 32-character combination of letters and 


numbers that uniquely identifies a document 
across all replicas of a database. 

Verifier 

Read-only. The name of the certificate that 
verified a signature, if a document is signed. 


Note The methods and properties listed in italics will be available in 
Lotus Notes Release 4.5. The UniversallD property will change to 
Read-Write in Release 4.5. The CopyAllltems method will have a new 
optional argument, replace, in Rel. 4.5. The GetNextItem method will be 
removed in Release 4.5. 

NotesDocumentCollection 

NotesDocumentCollection contains NotesDocument. 

A NotesDocumentCollection represents a subset of all the documents in a 
database. The documents in the subset are determined by the 
NotesDatabase method or property we use to search the database, which 
can be any of fhe following: 

• AllDocuments property 

• UnprocessedDocuments property 

• Search method 

• UnprocessedSearch method 

• FTSearch method 

• UnprocessedFTSearch method 

The Responses property in NotesDocument also returns a 
NotesDocumentCollection. 

Both NotesDocumentCollection and NotesView provide access to 
documents within a database. Use the NotesDocumentCollection object if: 

• You want to act on a specific sef of documents that meet certain criteria. 

• There is no view in the database that contains every document you 
need to search. 

• You do not need to navigate the documents' response hierarchies. 

Views are a more efficient means of accessing documents because they are 
already indexed by the database itself. However, they do not necessarily 
provide access to the documents that you want. 
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The documents in a collection are ordered when the collection results from 
a full fexf search; ofherwise, fhe documenfs are unordered. 


Method 

Description 

FTSearch 

Fetches the documents in a query. 

GetFirstDocument 

Gets the first document in a collection. 

GetLastDocument 

Gets the last document in a collection. 

GetNextDocument 

Given a document, finds the document 
immediately following it in a collection. 

GetNthDocument 

Given a position number, returns the document at 
that position in a collection. 

GetPrevDocument 

Given a document, finds the document 
immediately preceding it in a collection. 

PutAHInFolder 

Puts all documents in a folder. 

RemoveAll 

Removes all the documents in 
NotesDocumentCollection. 

RemoveAllFromFolder 

Removes all the documents from a folder. 

SaveAH 

Saves all the documents in 
NotesDocumentCollection. 

StampAU 

Stamps all the documents. 

UpdateAH 

Updates all the documents. 


Property 

Description 

Count 

Read-only. The number of documents in a 
collection. 

IsSorted 

Read-only. Indicates if the documents in a 
collection are sorted. A collection is sorted only 
when it results from a full text search of a 
database. 

Parent 

Read-only. The database that contains a document 
collection. 

Query 

Read-only. The text of the query that produced a 
document collection, if the collection results from 
a full text or other search. 


Note The mefhods lisfed in italics will be available in Release 4.5. 
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NotesEmbeddedObject 

The NotesEmbeddedObject class is contained by NotesDocument and 
NotesRichTextitem. it represents an embedded object, an object link, or a 
file attachment. Some methods and properties that are available for 
embedded and linked objecfs are unavailable for file affachments. 

We use fhe EmbedObjecf mefhod of NofesRichText fo create a 
NotesEmbeddedObject. There are three ways to access the class: 

• To access an object, object link, or attachment when you know its name 
and the rich text item that contains it, use the GetEmbeddedObject 
method of NofesRichTextifem. 

• To access all fhe objecfs, objecf links, and affachments in a particular 
rich text item, use the EmbeddedObjects property of 
NofesRichTextifem. 

• To access fhe objecfs and objecf links in a particular document, 
including those that are not contained within a particular rich text item, 
use the EmbeddedObjects property of NofesDocument. This property 
does not return file affachments or objects and object links created in 
Notes Release 3. 


Method 

Description 

Activate 

Causes an embedded object or object link to be loaded by 
OLE. 

Do Verb 

Given the name of a verb, executes the verb in an embedded 
object. 

ExtractFile 

Copies a file attachment to disk. 

Remove 

Permanently deletes an embedded object, object link, or file 
attachment. 


Property 

Description 

Class 

Read-only. The name of the application which created an 
object. 

FileSize 

Read-only. The size of an embedded object, object link, or 
file attachment, in bytes. 

Name 

Read-only. The name used to reference an embedded object 
or object link. 


Continued 
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Property 

Description 

Object 

Read-only. If an embedded object has been loaded into 
memory, returns the OLE handle (IUnknown or IDispatch 
handle). If the OLE object supports OLE Automation, you 
can invoke the methods and properties of the object using 
the handle. 

Parent 

Read-only. The rich text item that holds an object. 

Source 

Read-only. If the NotesEmbeddedObject is an embedded 
object or object link, this property returns the internal name 
that Notes uses to refer to the source document. If the 


NotesEmbeddedObject is a file attachment, this property 
returns the file name of the original file. 

Type 

Read-only. Indicates if a NotesEmbeddedObject is an 
embedded object, an object link, or a file attachment. 

Verbs 

Read-only. The verbs that an object supports, if the object is 
an OLE/2 embedded object. 


Note The DoVerb method of NotesEmbeddedObject is used differently 
depending on the platform and OLE server. Eor example, you use 
Embobj.DoVerb "&Open" in Windows 95 and Embobj.DoVerb "Edit" in 
Windows 3.1. Eor details on the OLE server, refer to the appropriate OLE 
server documentation. 

NotesForm 

The NotesEorm class will be available in Release 4.5. 


Method 

Description 

Remove 

Deletes a form from the database. 


Properties 

Description 


Aliases 

Read-only. String array of aliases. 

Eields 

Read-only. String array of field names. 

FormUsers 

Read-Write. String array of the form user names. 

IsSubForm 

Read-only. Indicates if the form is a subform. 

Name 

Read-only. Form name. 

ProtectReaders 

Read-Write. If true, does not replace $Readers item 
during replication. 

ProtectUsers 

Read-Write. If true, does not replace $FormUser item 
during replication. 

Readers 

Read-Write. String array of readers. 
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Notesinternational 

The Notesinternational class will be available in Release 4.5. All the 
properties here are Read-only. 


Property 

Description 

AMString 

Read-only. String that indicates before noon in 
12-hour time. 

CurrencyDigits 

Integer - number of digits after decimal point. 

CurrencySymbol 

String - the currency symbol, for example, the 
dollar sign in US. 

DateSep 

String - the character used to separate the parts of 
the date. 

DecimalSep 

String - the character used to separate the parts of 
a decimal number. 

IsCurrencySpace 

True if the currency symbol is separated by a 
space from the number. 

IsCurrencySuffix 

True if the currency symbol follows the number. 

IsCurrencyZero 

True if a decimal number that is a fraction has a 
zero before the decimal separator. 

IsDateDMY 

True if the date format is day-month-year. 

IsDateMDY 

True if the date format is month-day-year. 

IsDateYMD 

True if the date format is year-month-day. 

IsDST 

True if daylight savings time is in effect. 

IsTime24Hour 

True if the time is in 24-hour format. 

PMString 

String that indicates after noon in 12-hour time. 

ThousandsSep 

String - the character that separates numbers at 
the 1000s. 

TimeStep 

String - the character used to separate the parts of 
the time. 

TimeZone 

Integer - the time zone. 

Today 

String that means today. 

Tomorrow 

String that means tomorrow. 

Yesterday 

String that means yesterday. 
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Notesitem 


In the user interface. Notes displays items in a document through fields on 
a form. When a field on a form and an ifem in a documenf have fhe same 
name, fhe field displays fhe ifem (for example, fhe Subjecf field displays fhe 
Subjecf ifem). All of fhe ifems in a documenf are accessible fhrough 
LofusScripf, regardless of whaf form is used fo display fhe documenf in fhe 
user inf erf ace. 

The Nofesifem class is confained by NofesDocumenf. You can creafe 
a new Nofesifem objecf from one fhaf already exisfs using fhe 
CopylfemToDocumenf mefhod of Nofesifem or using fhe Copylfem or 
ReplacelfemValue mefhods of NofesDocumenf. You can also creafe one 
from scrafch using fhe New mefhod of Nofesifem or using fhe 
AppendIfemValue or ReplacelfemValue mefhods of NofesDocumenf. 

You musf call Save on fhe documenf if you wanf fhe modified documenf fo 
be saved fo disk. The documenf will nof display fhe new ifem in fhe user 
inferface unless fhere is a field of fhe same name on fhe form used fo 
display fhe documenf. 


Method 

Description 

New 

Creates a new Notesitem object. 

Abstract 

Abbreviates the contents of a text item. 

AppendToTextList 

For an item that's a text list, adds a new value to the 
item without erasing any existing values. 

Contains 

Given a value, checks if the value matches at least 
one of the item's values exactly. 

CopyltemToDocument 

Copies an item to a specified document. 

Remove 

Permanently deletes an item from a document. 


Property 

Description 

DateT ime V alue 

Read-Write. For a date-time item, returns a 
NotesDateTime object representing the value of the 
item. For items of other types, returns Nothing. 

IsAuthors 

Read-only. Indicates whether or not an item is of 
type Authors. An Authors item contains a list of 
Notes user names, indicating people who have 
Author access to a particular document. 

IsEncrypted 

Read-Write. Indicates if an item is encrypted. 


Continued 
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Property 

Description 

IsNames 

Read-only. Indicates if an item is a Names item. A 
Names item contains a list of Notes user names. 

IsProtected 

Read-Write. Indicates if a user needs at least Editor 
access to modify an item. 

IsReaders 

Read-Write. Indicates whether or not an item is of 
type Readers. A Readers item contains a list of Notes 
user names, indicating people who have Reader 
access to a particular document. 

IsSigned 

Read-Write. Indicates if an item contains a signature. 

IsSummary 

Read-Write. Indicates if an item can appear in a view 
or folder. 

LastModified 

Read-only. Date of the last modification. 

Name 

Read-only. The name of an item. 

Parent 

Read-only. The document that contains an item. 

SaveToDisk 

Read-Write. If true, then the item is written to disk 
on document save. 

Text 

Read-only. A plain text representation of an item's 
value. 

Type 

Read-only. The data type of an item. 

ValueLength 

Read-only. The size of an item's value in bytes. 

Values 

Read-Write. The value(s) that an item holds. 


Note The properties listed in italics will be available in Release 4.5. 

NotesLog 

NotesLog enables us to record actions and errors that take place during a 
script's execution. You can record actions and errors in a Notes database, a 
mail memo, or a file (for scripts that run locally). 

NotesLog is contained by NotesSession. To create a new log, you can use 
the New method of NofesLog or the CreateLog method of NofesSession. 
When you create a log using New, you can use one of fhe following 
mefhods fo open the log: 

• To log to a database, use the OpenNotesLog method. 

• To log to a mail memo, use the OpenMailLog method. 

• To log to a file (only available fo scripts running locally), use the 
OpenFileLog method. 
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Notes does not automatically log actions or errors. You must explicitly log 
each action and error using the following methods: 

• To log an action, use LogAction. 

• To log an error, use LogError. 


Method 

Description 

New 

Creates a NotesLog object. 

Close 

Closes a log. 

LogAction 

Records an action in a log. 

LogError 

Records an error in a log. 

LogEvent 

Sends a Notes event out to the network. Only scripts 
running on a server can use this method. 

OpenAgentLog 

Starts logging an agent event. 

OpenFileLog 

Starts logging to a specified disk file. This method 
returns an error if you call it on a server. 

OpenMailLog 

Opens a new mail memo for logging. The memo is 
mailed when the log's Close method is called, or when 
the object is deleted. 

OpenNotesLog 

Opens a specified Notes database for logging. 


Property 

Description 

LogActions 

Read-Write. Indicates if action logging is enabled or not. 

LogErrors 

Read-Write. Indicates if error logging is enabled or not. 

NumActions 

Read-only. The number of actions logged so far. 

NumErrors 

Read-only. The number of errors logged so far. 

OverwriteFile 

Read-Write. For a log that records to a file, indicates if 
the log should write over the existing file or append to 
it. This property has no effect on logs that record to a 
mail message or database. 

ProgramName 

Read-Write. The name that identifies the script whose 
actions and errors you're logging. The name is the same 
as the name specified with New or CreateLog. 


Note The methods listed in italics will be available in Release 4.5. 
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NotesName 


The NotesName class will be available in Release 4.5. NotesName is 
contained by NotesSession. All the properties of NotesName are Read-only. 


Method 

Description 

New 

Creates a new NotesName object. 


Property 

Description 


Abbreviated 

String - abbreviated format of hierarchical name 

ADMD 

Administration management domain name part of 
name 

Canonical 

String - canonical format of hierarchical name 

Common 

String - common name (CN=) component of 
hierarchical name 

Country 

String - common name (CN=) component of 
hierarchical name 

Generation 

Generation part of a name, for example, "]r." 

Given 

Given name part of a name 

Initials 

Initials part of name 

IsHierarchical 

True if the name is hierarchical 

Keyword 

Country\ organizationX organizational unit 

1\organizational unit 2\organizational unit 

3 \ organizational unit 4 

Organization 

String - organization (0=) component of hierarchical 
name 

OrgUnitl 

String - first organizational unit (OU=) component of 
hierarchical name 

OrgUnit2 

String - second organizational unit (OU=) component 
of hierarchical name 

OrgUnitS 

String - third organizational unit (OU=) component of 
hierarchical name 

OrgUnitd 

String - fourth organizational unit (OU=) component 
of hierarchical name 

PRMD 

Private management domain name part of name 

Surname 

Surname part of name 
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NotesNewsletter 

NotesNewsletter is contained by NotesSession and contains 
NotesDocument. 

To create a new NotesNewsletter object, you use NotesDocumentCollection 
containing the documents you want, or the New method of 
NotesNewsletter, or the CreateNewsletter method of NofesSession. If you 
create a newsletter using New, there are two things you can do with it: 

• Use the FormatDocument method to create a new document with a 
rendering (picture) of one of fhe documents in the collection. 

• Use the FormatMsgWithDoclinks method to create a new document 
with links to each of fhe documents in the collection. 


Method 

Description 

New 

Creates a new NotesNewletter object. 

FormatDocument 

Creates a new document in the given database, 
containing a rendering (picture) of a specified 
document in the newsletter's collection. 

FormatMsgWithDoclinks 

Creates a newsletter document in the given 
database that contains a link to each document in 
the newsletter's collection. 


Property 

Description 

DoScore 

Read-Write. For a newsletter document created 
using the FormatMsgWithDoclinks method, 
indicates if the newsletter includes each 
document's relevance score. 

DoSubject 

Read-Write. For a newsletter document created 
using the FormatMsgWithDoclinks method, 
indicates if the newsletter includes a string 
describing the subject of each document. 

SubjectItemName 

Read-Write. For a newsletter document created 
using the FormatMsgWithDoclinks method, 
indicates the name of the item on a newsletter's 
documents which contains the text you want to 
use as a subject line. 
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NotesRichTextItem 


NotesRichTextItem is a derived class based on Notesitem. It is contained by 
NotesDocument and contains NotesEmbeddedObject. 

To create a new NotesRichTextItem object, use the New method of 
NotesRichTextItem or the CreateRichTextItem method of NofesDocument. 
Given a document. New creates a rich text item in the document, with the 
name you specify. 

To access an exisfing NofesRichTextIfem objecf, use fhe GefFirsfIfem and 
GefNextIfem mefhods of NofesDocument. 

Because NotesRichTextItem inherits from Nofesifem, all of fhe Nofesifem 
properties and methods can be used on a NotesRichTextItem, too. 

When you change the value of a NofesRichTextIfem objecf, fhe change is 
nof writfen to disk until you call the Save method for the parent 
NotesDocument. 


Method 

Description 

New 

Creates a new NotesRichTextItem object. 

AddNewLine 

Appends one or more new lines (carriage returns) to 
the end of a rich text item. 

AddTab 

Appends one or more tabs to the end of a rich text 
item. 

AppendDocLink 

Given a database, view, or document to link to, adds a 
link to the end of a rich text item. 

AppendRTFile 

Appends the contents of a rich text file (composed of 
compound document records) to the end of a rich text 
item. 

AppendRTItem 

Appends the contents of one rich text item to the end 
of another rich text item. 

AppendText 

Appends text to the end of a rich text item. The text is 
rendered with the current style of the item (such as 
bold, or italicized). 

EmbedObject 

Given the name of a file or an application, does one of 
the following: Attaches the file you specify to a rich 
text item, or embeds an object in a rich text item. The 
object is created using either the application or the file 
you specify, or places an object link in a rich text item. 
The link is created using the file you specify. 

GetEmbeddedObject 

Given the name of a file attachment, embedded object, 
or object link in a rich text item, returns the 
corresponding NotesEmbeddedObject. 

GetFormattedText 

Returns the contents of a rich text item as plain text. 
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Property 

Description 

EmbeddedObjects 

Read-Write. All the embedded objects, object links, 
and file attachments contained in a rich text item. 


Note When you use the EmbedObject method of NotesRichTextItem in 
Visual Basic using Notes classes through OLE Automation, the argument 
type of fhe mefhod is type number rather than type constant used in 
LotusScript. 


Type Constant 

Type Number 

EMBED_ATTACHMENT 

1454 

EMBED_OBJECT 

1453 

EMBED_OBJECTLINK 

1452 

Tip If Visual Basic cannof recognize a type constant, you can always use 
Message Cstr (TypeConstant) in LotusScript to find out the t 5 ^e number. 

NotesSession 


The NotesSession class represents the Notes environment of fhe current 
script, providing access to environment variables, address books, 
information about the current user, and information about the current 

Notes platform and release number. 

If contains NotesAgent, NotesDatabase, NotesDbDirectory, 

NotesDateTime, NotesLog, and NotesNewsletter. In Notes Release 4.5, it 
will contain the Noteslnternational and NotesDateRange classes. 

Method 

Description 

New 

Creates a new NotesSession object. 

Close 

Closes a session. Any objects contained within the 
session become invalid once you close it. 

CreateDateRange 

Given a NotesDateRange object which represents 
the date range you want. 

CreateDateTime 

Given a string that represents the date and time 
you want, creates a new NotesDateTime object 
that represents that date and time. When used 
with OLE automation, this method allows you to 
create a NotesDateTime object without using New. 

CreateLog 

Creates a new NotesLog object with the name you 
specify. When used with OLE automation, this 
method allows you to create a NotesLog object 
without using New. 


Continued 
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Method 

Description 

CreateN ewsletter 

Given a NotesDocumentCollection containing the 
documents you want, creates a new 
NotesNewsletter. When used with OLE 
automation, this method allows you to create a 
NotesNewsletter object without using New. 

FreeTimeSearch 

Given a NotesDateRange array. 

GetDatabase 

Creates a NotesDatabase object that represents the 
database located at the server and file name you 
specify, and opens the database, if possible. When 
used with OLE automation, this method allows 
you to create a NotesDatabase object without 
using New. It does not create a new database on 
disk. 

GetDBDirectory 

Creates a new NotesDbDirectory object using the 
name of the server you want to access. When used 
with OLE automation, this method allows you to 
create a NotesDbDirectory object without using 
New. 

GetEnvironmentString 

Given the name of a string environment variable, 
retrieves its value. 

GetEnvironmentV alue 

Given the name of a numeric environment 
variable, retrieves its value. 

SetEnvironment V ar 

Sets the value of a string or numeric environment 
variable. 

UpdateProcessedDoc 

Marks a document as processed by an agent. 


Property 

Description 

AddressBooks 

Read-only. The Address Books, both public and 
personal, that are known to the current script. 

CommonUserName 

Read-only. The common name portion of the 
current user's name. 

CurrentAgent 

Read-only. The agent that's currently running. 

CurrentDatabase 

Read-only. The database in which the current 
script resides. This database may or may not be 


open. 

DocumentContext 

Read-only. If the agent is invoked from the Notes 
API, then this might contain a NotesDocument. 
Used to pass arguments to an agent. 

Continued 


74 LotusScript for Visual Basic Programmers 



Property 

Description 

EffectiveUserName 

Read-only. The user name that is in effect for the 
current script. 

IsOnServer 

Read-only. Indicates if a script is running on a 
server. 

International 

Read-only. Returns a Notesinternational object. 

LastExitstatus 

Read-only. The exit status code returned by the 
Agent Manager the last time the current agent ran. 

LastRun 

Read-only. The date when the current agent was 
last executed. 

NotesVersion 

Read-only. The release of Notes in which the 
current script is running. 

Platform 

Read-only. The name of the platform in which the 
current script is running. 

SavedData 

Read-only. A document that an agent script uses 
to store information in-between invocations. The 
script can use the information in this document 
the next time the script nms. 

UserName 

Read-only. The current user's name. 


Note The properties and methods listed in italics will be available in 
Release 4.5. The SetEnvironmentVar method will have a new optional 
argument, system, in Release 4.5. The Close method will be removed in 
Release 4.5. 
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NotesTimer 

The NotesTimer class will be available in Release 4.5. 


Method 

Description 

New 

Creates a new NotesTimer object. 


Property Description 

Comment Read-Write. Any string to identify the timer. 

Enabled Read-Write. True if the timer is enabled. 

Interval Read-Write. Number of seconds in the timer's interval. 


NotesView 

The NotesView class is contained by NotesDatabase, and contains 
NotesDocument and NotesViewColumn. It will contain 
NotesDocumentCollection in Release 4.5. 

You access a view or folder through the NotesDatabase object that contains 
the view or folder. There are fwo ways: 

• To access a view or folder when you know ifs name or synonym, use 
fhe GefView mefhod of NofesDafabase. 

• To access all fhe views and folders in a dafabase, use fhe Views 
properfy of NofesDafabase. 

Bofh opfions refurn NofesView objecfs fhaf represenf public view(s) and/or 
folder(s) in fhe dafabase. If a scripf runs on a worksfafion, fhe NofesView 
objecf may also represenf personal views and folders. 

To access a view or folder when we have a documenf fhaf was refrieved 
from fhe view or folder, use fhe ParenfView properfy of NofesDocumenf. 

Bofh NofesDocumenfCollecfion and NofesView provide access fo 
documenfs wifhin a dafabase. Use fhe NofesView objecf if: 

• There is a view or folder in fhe dafabase fhaf confains all fhe documenfs 
you wanf fo search. 

• You need fo navigafe fhrough fhe documenfs' response hierarchies. 

• You wanf fo access documenfs as quickly as possible. 

• You wanf fo find a documenf by ifs key in a view. 

• You wanf fo access documenfs in sorfed order. 
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Views are the more efficient means of accessing documents because they 
are already indexed by the database itself. 


Method 

Description 

Clear 

Clears the full text search filtering on a view. 

FTSearch 

Conducts a full text search on all documents in a 
view and filters the view so that it represents 
only those documents that match the full text 
query. This method does not find word variants. 

GetAllDocumentsByKey 

Finds all documents based on its Column value 
in a view. 

GetChild 

Given a document in a view, returns the first 
response to the document. 

GetDocumentBvKev 

Finds a document based on its column values 
within a view. You create an array of strings 
(keys), where each key corresponds to a value in 
a sorted and categorized column in the view. 

The method returns the first document whose 
column values match each key in the array. 

GetFirstDocument 

Returns the first document in a view. This is the 
same document you see when you scroll to the 
top of the view in the Notes user interface. 

GetLastDocument 

Returns the last document in a view. This is the 
same document you see when you scroll to the 
bottom of the view in the Notes user interface. 

GetNextDocument 

Given a document in a view, returns the 
document immediately following it. 

GetNextSibling 

Given a document in a view, returns the 
document immediately following the given 
document at the same level. If you send the 
method a main document, the next main 
document in the view is returned; if you send a 
response document, the next response document 
with the same parent is returned. 

GetNthDocument(n) 

Given a number, returns the document at the 
given position in a view. 

GetParentDocument(doc) 

Given a response document in a view, returns its 
parent document. 

GetPrevDocument 

Given a document in a view, returns the 
document immediately preceding. 


Continued 
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Method 

Description 

GetPrevSibling 

Given a document in a view, returns the 
document immediately preceding the given 
document at the same level. 

MarkRead 

Marks the document as read. 

MarkUnread 

Marks the document as unread. 

Refresh 

Updates a view's contents with any changes that 
have occurred to the database since the 


NotesView object was created, or since the last 
Refresh. 

Remove 

Permanently deletes a view from a database. 


Property 

Description 

Aliases 

Read-only.The alternative names for the view. 

AutoUpdate 

Read-Write. Boolean. If true, the view will 
update itself automatically. 

NotesViewColumnArray 

Read-only. All the columns in a view. 

Created 

Read-only. The date that a view was created. 

IsCalendar 

Read-only. Indicates whether or not a view is a 
calendar view. 

IsDefaultView 

Read-only. Indicates whether or not a view is the 
default view of the database. 

IsFolder 

Read-only. Indicates whether a NotesView object 
represents a folder. 

LastModifed 

Read-only. The date that a view was last 
modified. 

Name 

Read-only. The name of a view. 

Parent 

Read-only. The database to which a view 
belongs. 

ProtectReaders 

Read-Write. If true, does not replace $Readers 
item during replication. 

Readers 

Read-Write. Indicates the readers of the view. 

UniversallD 

Read-only. The Universal ID of a view, which is 
a 32-character combination of letters and 
numbers that uniquely identifies a view across 
all replicas of a database. 
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Note The methods and properties listed in italics will be available in 
Release 4.5. The max argument of FTSearch will be optional in Release 4.5. 
The GetDocumentByKey method will provide a new optional argument, 
exact, in Release 4.5. 

NotesViewColumn 

The NotesViewColumn class is contained by NotesView. You access an 
existing NotesViewColumn object through the view or folder thaf contains 
it. Use the Columns property of NofesView. 


Property 

Description 

Formula 

Read-only. The ©function formula for a column, if it 
exists. 

IsCategory 

Indicates if a column is categorized. 

IsHidden 

Indicates if a column is hidden. 

IsRespones 

Read-only. Indicates if a column contains only response 
documents. 

IsSorted 

Read-only. Indicates if a column is sorted. 

ItemName 

Read-only. The name of the item whose value is shown 
in the column. For columns whose values are simple 
functions or formulas, returns an automatically 
generated internal name. 

Position 

Read-only. The position of a column in its view. 

Columns are numbered from left to right, starting with 

1. 

Title 

Read-only. The title of a column, if any. 


Notes Ul (front_end) Classes 

There are fwo Nofes Ul classes. 


Class 

NotesUlW orkspace 
NotesUIDocument 
NotesUIView 
NotesUIDatabase 


Description 

Provides access to the current workspace. 

Models the behavior of a Notes document window. 
Provides access to the current view. 

Provides access to the current database. 


Note The classes listed in italics will be available in Release 4.5. 


Chapter 3: LotusScript Notes Classes 79 



NotesUlWorkspace 

NotesUIWorkspace contains NotesUIDocument. To create a new 
NotesUlWorkspace object, we use the New method. 


Method 

Description 

New 

Creates a new NotesUlWorkspace object. 

AddDatabase 

Adds a database to the workspace. 

CheckAlarms 

Checks the alarms. 

ComposeDocument 

Using a database and form you specify, creates a 
new document and displays it on the workspace. 

DialogBox 

Brings up a dialog box that displays the current 
document (either open or selected in a view) using 
a form you specify. The user interacts with the 
form and document as usual, selecting OK or 
Cancel when finished. 

EditDocument 

Opens the current document in a mode you 
specify. 

EditProfile 

Edits the profile document. 

EnableAlarms 

Enables the alarms. 

OpenDatabase 

Opens a database to a view you specify. 

URL Open 

Opens a URL. 


Property 

Description 

CurrentDocument 

Returns a NotesUIDocument object representing 
the document that's currently open. 


Note The methods listed in italics will be available in Release 4.5. The 
ComposeDocument and DialogBox, methods will have new arguments. The 
EditDocument method will have two new optional arguments, document 
and Readonly. The OpenDatabase method will provide several options in 
Release 4.5. 

NotesUIDocument 

NotesUIDocument is contained by NotesUlWorkspace and contains 
NotesDocument. There are four ways to get the current document: 

• You can use the CurrentDocument property of NofesUlWorkspace. 

• If you are writing a script that responds to a NotesUIDocument event, 
use the source parameter from one of fhe events. 
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• If you want to create a new document in a database and access it, use 
the ComposeDocument method of NotesUIWorkspace. 


• If you want to open the currently highlighted document and access it, 
use the EditDocument method of NotesUIWorkspace. 


Method 

Description 

Categorize 

Given the name of a category, places a document in 
the category. 

Clear 

Deletes the current selection from a document. The 
current selection can be anything in an editable field, 
such as text or graphics. 

Close 

Closes a document. The NotesUIDocument is no 
longer available once you call this method. 

CollapseAllSections 

Collapses all the sections in a document. 

Copy 

Copies the current selection in a document to the 
Clipboard. The current selection can be anything in 
the document, such as text or graphics. 

CreateObject 

In a document in edit mode, creates an OFF object in 
the current rich text field. 

Cut 

Cuts the current selection from a document and 
places it on the Clipboard. The current selection can 
be anything in an editable field, such as text or 
graphics. 

DeleteDocument 

Marks the current document for deletion and closes 
it. The NotesUIDocument object is no longer 
available once you call this method. 

DeselectAll 

Deselects any selections in a document. 

ExpandAllSections 

Expands all the sections in a document. 

FieldAppendText 

Appends a text value into a field in a document 
without removing the existing contents of the field. 

FieldClear 

Clears the contents of a field in a document. 

FieldContains 

In an open document, checks if a field contains a 
specific text value. 

FieldGetText 

In a document in read or edit mode, returns the 
contents of a field you specify, as a string. If the field 
is of type numbers or date-time, its contents are 
converted to a string. 

FieldSetText 

Sets the value of a field on a document. The existing 
contents of the field, if any, are written over. 


Continued 
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Method 

Description 

FindFreeTimeDialog 

Finds free time dialog. 

Forward 

Creates a new mail memo with the contents of a 
document. The user can enter recipients and mail the 
forwarded document like any other mail memo. 

GetObject 

Given a name, returns a handle to the OLE object of 
that name. 

GotoBottom 

Places the cursor in the last editable field in a 
document. 

GotoField 

Given a field name, puts the cursor in the specified 
field in a document. 

GotoNextField 

Places the cursor in the next field in a document. The 
next field is the one below and to the right of the 
current field. 

GotoPrevField 

Places the cursor in the first editable field in a 
document. 

GotoTop 

Places the cursor in the first editable field in a 
document. 

InsertText 

Inserts a text value at the current cursor position in a 
document. 

Paste 

Pastes the contents of the Clipboard at the current 
cursor position in a document. 

Print 

Prints the current document. If one or more 
parameters are specified, automatically prints the 
document. If no parameters are specified, or if the 
first parameter is omitted, displays the File Print 
dialog box. 

Refresh 

Refreshes a document. When you refresh a 
document, its computed fields are recalculated. 

RefreshHideFormulas 

Recalculates the hide-when formulas in the current 
document's form. 

Reload 

Refreshes the current document with any changes 
that have been made to the corresponding back-end 
document. Refreshing the current document updates 
its representation in memory, and visually on the 
workspace, to reflect the changes that have been 
made to the back-end document. 

Save 

Saves a document. 


Continued 
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Method 

Description 

SaveNew V ersion 

Saves a copy of a document as a new version. 

SelectAll 

In a document in edit mode, selects the entire 
contents of the current field. In a document in read 
mode, selects the entire contents of the document. 

Send 

Mails a document. 


Property 

Description 

AutoReload 

Read-Write. Indicates whether or not the current 
document should be refreshed whenever the 
corresponding back-end document changes. 

CurrentField 

Read-only. The name of the field that the cursor is 
in. 

Document 

Read-only. The back-end document that corresponds 
to the currently open document. 

EditMode 

Read-Write. Indicates if a document is in edit mode. 

FieldHelp 

Read-Write. Indicates if field help for a document is 
displayed. 

HiddenChars 

Read-Write. Indicates if the hidden characters in a 
document (such as tabs and carriage returns) are 
displayed. 

HorzscrollBar 

Read-Write. Indicates if a document's horizontal 
scroll bar is displayed. 

IsNewDoc 

Read-only. Indicates if a document is new. A new 
document is one that hasn't been saved. 

InPreviewPane 

True if the document is in the preview pane. 

PreviewDocLink 

Read-Write. Indicates if a link's preview pane is 
displayed. 

PreviewParentDoc 

Read-Write. Indicates if the parent document's 
preview pane is displayed. 

Ruler 

Read-Write. Indicates if the ruler is displayed. 

WindowTitle 

Read-only. The window title of a document. 
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NotesUIDatabase 


The NotesUIDatabase class will be available in Release 4.5. It is contained 
by NotesUlWorkspace and contains NotesDatabase and 
NotesDocumentCollection. 

Method 

Description 

OpenView(viewname) 

Opens a view in the current database by view 
name. 


Property 

Description 

Database 

Documents 

Read-only. Refer to back-end database object of 
the current database. 

Read-only. Indicates all the document arrays in the 
current database. 


NotesUIView 

The NotesUIView class will be available in Release 4.5. It is contained by 
NotesUIDatabase and contains NotesView and NotesDocumentCollection. 


Property 

Description 

CalendarDateTime 

Read-only. Indicates the calendar date time. 

Documents 

Read-only. Indicates the back-end document 
collection of the current view. 

View 

Read-only. Indicates the back-end view of the 
current view. 
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Chapter 4 

Lotus Notes as an OLE 2 Automation Server 


You can develop Notes applications in Visual Basic using the Notes classes. 
This chapter shows you how to do this. 

in this chapter, we will discuss how to: 

• Use Notes classes in Visual Basic 

• Declare Notes classes in Visual Basic 

• Use the Notes class hierarchy in Visual Basic 

• Handle errors in Visual Basic using Notes classes. 

Note The software environment used in this chapter is Windows 95, Lotus 
Notes 4.1 (32-bit) and Visual Basic 4.0 (32-bit). 


Using Notes Classes in Visual Basic through OLE Automation 

We use OLE automation to develop Notes applications in Visual Basic 
using Notes classes. 

OLE automation is a widely accepted object model used by many 
applications to provide objects in a consistent way to other applications, 
development tools, and macro languages. OLE servers expose their objects 
to other applications, whereas client applications use those objects. Objects 
contain data (properties) and the functions (methods) used to perform an 
acfion with the object. You can call upon an OLE automation object's code 
to perform a variefy of fasks fhaf you do nof want to, or cannot, perform in 
your own code. 

Lofus Nofes Release 4 is an OLE aufomafion server. You can develop your 
own Nofes applicafions in Visual Basic and manipulafe objecfs in 
LofusScript. 
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The following figure shows how if works: 



How Visual Basic and LotusScript Work with OLE Automation 

You can create a reference to Notes objects, such as NotesDatabase, 
NotesACL, NotesLog and NotesDocument, in your code. NotesSession, 
and NotesUiWorkspace are objects that can be created externally. You can 
set a reference to them using the CreateObject method from outside the 
LotusScript that created the object. 

Those objects are at the highest level of the Notes object hierarchy. Use a 
method from a higher level object in the hierarchy to get a reference to 
other objects, such as NotesDatabase, NotesDbDirectory, NotesACL, 
NotesLog, Notesitem, and NotesUiDocument. 

After you have declared a variable that references an OLE automation 
object, the object can be manipulated in Visual Basic using the 
object.property syntax to set and return the object's property values, or by 
using the objec.method syntax to use methods on the object. 

When you are finished using a Notes object, clear any variables that 
reference the Notes objects so the Notes object can be released from 
memory. To clear a variable, set it to Nothing. 

Let's try it. 

Let's create our first Visual Basic application using Notes classes, in this 
example we use a TEST database which was created using the Discussion 
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(R4) template. The database file - test.nsf - is in your default Notes database 
directory. For information on how to create the database, refer to Chapter 5. 

1. Use Visual Basic to create a form like fhe following: 



2. Put the following code on the Create Document button: 

Private Sub Coinmandl_Click () 

Dim session As Object 
Dim db As Object 
Dim doc As Object 

Set session = CreateObject("Notes.NotesSession") 

Set db = session.GetDatabase, "test.nsf") 

Set doc = db.CreateDocument0 
doc.Form = "Main Topic" 
doc.Subject = Forml.Texts.Text 
doc.Body = Forml.Texts.Text 
Call doc.Save(True, False) 

End Sub 

Following is an explanation of fhe code. 

To access fhe Nofes objecfs, we declare them as OLE objects in Visual 
Basic. 

Dim session As Object 

Dim db As Object 
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Dim doc As Object 

We create a reference to the Notes object that is created externally. 

Set session = CreateObject("Notes.NotesSession") 

We use the Notes object hierarchy to create the object db to access the 
Notes database TEST on the local server. For the GetDatabase method, 
the first parameter is the server name, the second parameter is the 
database file name. If the server is a local server, specify an empty 
string, as in our example. 

Set db = session.GetDatabase("", "test.nsf") 

We use the Notes hierarchy to create the doc object to access a Notes 
document. 

Set doc = db.CreateDocument() 

We use the Main Topic form to create the document. 

doc.Form = "Main Topic" 

Fill the Subject and Body text fields with the contents of fhe fext boxes 
in the Visual Basic application. 

doc.Subject = Forml.Texts.Text 

doc.Body = Forml.Texts.Text 

We use the Save method to save the document. We want the document 
to be saved even if someone else edits and saves the document while 
the application is running. So we set True in the first argument. 
Otherwise when someone else edits the document while the application 
is running, the second argument determines what happens. 

Call doc.Save(True, False) 

3. Put the following code on the Exit command button: 

Private Sub Command2_Click() 

Set db = Nothing 
Set session = Nothing 
Unload Forml 
End Sub 

Following is an explanation of fhe code. 

We release objecf db and objecf session before we exit the application. 

Set db = Nothing 
Set session = Nothing 
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We exit the application and unload forml. 

Unload Forml 

4. Let's have a look at how the application works. Choose Run - Start from 
the menu to rim the application. 

5. Fill the Subject field and Body field on fhe form. 

6. Click fhe Creafe Documenf buffon fo creafe a new documenf in fhe Tesf 
dafabase. 



7. Look af your Tesf dafabase on your Nofes workspace. A new documenf 
has been creafed. If looks like fhis: 
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Declaring Notes Classes in Visual Basic 

When we use LotusScript Notes objects in Visual Basic, the declaration of 
the Notes objects is different from the declaration in LotusScript. In 
LotusScript, we declare Notes objects as objects of their specific Nofes 
classes. For example: 

Dim session As NotesSession 

Dim db As NotesDatabase 

Dim doc As NotesDocument 

Buf in Visual Basic, we declare Nofes objecfs simply as an objecf. Then we 
sef a reference fo fhe objecf. For example: 

'declare Notes objects as Object 

Dim session As Object 

Dim db As Object 

'set a reference to the Notes Objects 

set session = CreateObject ("Notes.NotesSession") 

set db = session.GetDatabase("","test.nsf") 

Note By changing the declaration of fhe Nofes objecfs, you can run the 
Visual Basic code in LotusScript. 

As we declare Notes objects as objects in Visual Basic, we cannot use the 
New method of fhe classes. We use fhe New mefhod to declare a new object 
in LotusScript. For example: 

Dim db as New NotesDatabase("","discuss4.ntf") 

Dim doc as New NotesDocument 


Using the Notes Class Hierarchy in Visual Basic 

There is a hierarchical relationship for objecf classes. Higher hierarchical 
classes contain the lower ones. Each class has defined members, properties 
and methods. Using these members, you can access other objects. The 
relationship of containment and access means that the higher class has the 
property or the method to access the lower one. For example, you can see 
all the views when you open the database. This means that the opened 
database(object) in the workspace includes the views(object). Furthermore, 
you can see the documents when you select one of fhe views. This means 
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that your selected view(object) contains the documents(object). The 
following figure shows fhe hierarchical relafionship for Nofes objecf classes. 


Front_End 


Back_End 



Note This charf only includes fhe 18 classes available in Lofus Nofes 
Release 4.1. There will be an additional six classes available in Release 4.5. 
Four of fhem can be used in Visual Basic: Nofeslnfernafional, NofesName, 
NofesDafeRange and NofesTimer. 


Chapter 4: Lotus Notes as an OLE 2 Automation Server 91 












In Visual Basic, we can access the Notes objects in one of two ways: 

• Directly, if fhe objecf can be created externally. 

• Indirectly, if the object is a dependent object. You can get a reference fo 
it from anofher objecf higher in the Notes class hierarchy. 

NotesSession and NotesUIWorkspace are object classes that can be created 
externally. We can access these two classes directly from Visual Basic using 
fhe CreafeObjecf function. NofesSession and NofesUIWorkspace are af fhe 
highesf level of fhe hierarchy. Ofher objecf classes are dependent object 
classes, and can be accessed only by using a method or a property of one of 
the two classes. 

In our previous example. Create Document, we created the externally 
creatable object session first. Then we used a method of fhe session fype 
objecf fo access fhe lower-level class db. 

Lef's look af some examples: 

Example 

This example accesses fhe current document in Notes Workspace. 

Dim workspace As Object 
Dim UIdoc as Object 

set workspace = CreateObject ("Notes.NotesUIWorkspace") 
set UIdoc = workspace.CurrentDocument() 

To access the current document (NotesUIDocument object) in Visual Basic, 
we first need to get a reference from NofesUIWorkspace. Then we use fhe 
CurrentDocument property of fhe NofesUIWorkspace class fo gef fhe 
reference fo fhe NofesUIDocument class. We declare workspace as an objecf 
which references NofesUIWorkspace. We declare UIdoc as an objecf which 
references NofesUIDocument. 

Dim workspace As Object 

Dim UIdoc As Object 

Create an externally creatable object. 

set workspace = CreateObject ("Notes.NotesUIWorkspace") 

Use the externally creatable object to access a lower-level object doc. 
set UIdoc = workspace.CurrentDocument() 
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Example 

This example accesses the Notes view called "By Author". 

Dim session As Object 
Dim db As Object 
Dim view As Object 

Set session = CreateObject ("Notes.NotesSession") 

Set db = session.GetDatabase"test.nsf") 

Set view = db.GetView ( "By Author") 

To access the NotesView class, we will get the reference to NotesView from 
fhe NofesDatabase class. Since NofesDafabase is nof an externally creatable 
object, we will get its reference from a higher-level class of fhe hierarchy, 
which is NofesSession. We gef fhe reference fo NofesDatabase using the 
GetDatabase method of fhe NofesSession class. Then we gef fhe reference fo 
NofesView using the GetView method of NofesDatabase. 

We declare session as an object which references NofesSession. 

Dim session As Object 

We declare db as an objecf which references NofesDatabase. 

Dim db As Object 

We declare view as an object which references NofesView. 

Dim view As Object 

We gef fhe reference fo NofesSession by using the GreateObject function of 
Visual Basic, and sfore if in session. 

Set session = CreateObject ("Notes.NotesSession") 

We gef fhe reference fo NofesDatabase using the GetDatabase method of 
NofesSession, and sfore if in db. 

Set db = session.GetDatabase ("","test.nsf") 

We gef fhe reference fo NofesView and sfore if in view. 

Set view = db.GetView ( "By Author") 

Example 

This example shows how we access Nofeslfem in the current Notes 
document. 

Dim workspace As Object 
Dim UIdoc As Object 
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Dim doc As Object 
Dim item As Object 

Set workspace = CreateObject ("Notes.NotesUIWorkspace") 

Set UIdoc = workspace.CurrentDocument 

Set doc = UIdoc.Document 

Set item = doc.GetFirstItem ("Subject") 

The item we are accessing is an item in the current document. So we need 
to get the document reference from NofesUIDocument. This is nof an 
externally creatable object. Therefore, we firsf gef fhe reference from 
NofesUlWorkspace fo gef fhe reference fo NofesUIDocument and then to 
the other lower-level classes. 

We declare workspace, UIdoc and doc as object. 

Dim workspace As Object 
Dim UIdoc As Object 
Dim doc As Object 

We declare item as an object which references Nofeslfem. 

Dim item As Object 

We gef fhe reference from NofesUlWorkspace and NofesUIDocument. 

Set workspace = CreateObject ("Notes.NotesUIWorkspace") 

Set UIdoc = workspace.CurrentDocument 

We get a reference fo NofesDocument using the Document property of 
NofesUIDocument, and store it in doc. 

Set doc = UIdoc.Document 

We get reference fo Nofeslfem using the GetFirstItem method of 
NofesDocument to get the first Item named "Subject". 

Set item = doc.GetFirstItem ("Subject") 

Note When using Notes classes through OLE automation in Visual Basic, 
for some mefhods, you musf use tj^e numbers in arguments rather than 
type constants which are used in LotusScript. However, you can always get 
the tj^e number using "Messagebox Cstr (TypeConstant) " in 
LotusScript. For more information about type numbers, refer to Chapter 3. 
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Error Handling 


There are three kinds of errors you can encounter: 

• Compile errors 

• Run-time errors 

• Logic errors 

Compile Errors 

Compile errors result from incorrecfly consfrucfed code. If you misfype a 
ke 5 nvord, omit some necessary punctuation, or use a Next statement 
without a corresponding For statement. Visual Basic detects these errors 
when you compile the application. 

Compile errors include errors in syntax. If you have selecfed the Auto 
Syntax Check option in the Environment tab on the Options dialog box. 
Visual Basic will display an error message as soon as you enter a S 5 mtax 
error in the code window. 

To set the Auto Syntax check option: 

1. From the Tools menu, select Options, and click the Environment tab on 
the Options dialog box. 

2. Select Auto Syntax Check. 

Run-time Errors 

Run-time errors occur (and are detected by Visual Basic) when a statement 
attempts an operation that is impossible to carry out. 

When we use Notes object classes in Visual Basic the error-handling code is 
especially important because code from LofusScript is used remofely from 
within your Visual Basic application. Where possible, you should include 
code to handle errors that LotusScript may generate. When there is a 
run-time error generated in a Notes object, LotusScript handles the errors it 
can handle, and regenerates the errors which it cannot handle. Visual Basic 
will automatically remap untapped errors, and the error-handling code in 
your application is needed to handle the errors. 

In applications that use Notes objects and derived classes based on Notes 
objects, it becomes more difficult to determine where an error occurs, 
particularly if it occurs in a Notes LotusScript object. 
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The following figure shows a Visual Basic applicafion fhaf consisfs of a 
form module, which references a class module, which in furn references a 
LofusScripf Nofes ACL objecf. 



Regenerating Errors between Forms, Classes, and OLE Automation Notes 
Objects 

LotusScript handles the part of the error arising in the Notes object, if 
LotusScript objects cannot handle a particular error arising in the 
NotesACL, but regenerate it instead. Visual Basic will pass the error to the 
referencing object, MyClassACL. Visual Basic automatically remaps 
untapped errors arising in objects outside of Visual Basic as error code 440. 

The MyClassACL object can either handle the error (preferable), or 
regenerate it. The OLE interface specifies that any object regenerating an 
error that arises in a referenced object should not simply propagate the 
error (pass it as error code 440), but should instead remap the error number 
to something meaningful. When you indicate the error condition, if your 
handler can determine what the error is, it should map it to an undefined 
error number. Add the new number to the intrinsic Visual Basic constant 
vbObject Error to notify other handlers that this error was raised by your 
object (MyClassACL). 

Whenever possible, a class module (MyClassACL module in our case) 
should try to handle every error that arises in the object, it references errors 
that are not handled by that object. However, there are some errors that it 
cannot handle because it cannot anticipate them. There are also cases where 
it is more appropriate for the referencing object to handle the error, rather 
than the referenced object. 

When an error occurs in the form module. Visual Basic raises one of the 
predefined Visual Basic error numbers as described in the online Help. 
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When you regenerate an error, leave the error object's other properties 
unchanged. If the raised error is not trapped, the Source and Description 
properties can be displayed to help the user take corrective action. 

A class (MyClassALC) module might include the error handler to 
accommodate any error it might trap, regenerating those it is unable to 
resolve. 

When you are debugging an application that has a reference fo an OLE 
aufomafion objecf or a class defined in a class module, you may find it 
confusing to determine which object generates an error. To make this easier, 
you can select the Break in Class module option on the Advanced tab of fhe 
Options dialog box (available from the Tools menu). With this option 
selected, an error arising in a form or sfandard module will invoke an error 
handler, if one is available. An error in a class module or an objecf in 
anofher application that is running in another instance of Visual Basic will 
cause fhaf class fo enter the debugger's break mode, allowing you to 
analyze the error. An error arising in a compiled object will not display the 
debug window in break mode; rather, such errors will be handled by the 
object's error handler, or trapped by the referencing module. 

Logic Errors 

Logic errors occur when an applicafion doesn't perform the way it was 
intended. An application can have syntactically valid code, run without 
performing any invalid operations, and yef produce incorrecf results. Only 
by testing the application and analyzing results can you verify thaf fhe 
applicafion is performing correcfly. You can use fhe Visual Basic Debugging 
fools fo fix logic errors. 
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Chapter 5 

Converting HiTest Applications 


HiTest Tools for Visual Basic is a 16-bit product, it can only work with 
16-bit Visual Basic and the 16-bit version of Lofus Nofes (Lofus Nofes 
Release 3 and Release 4 for Windows 3.1). 

You can convert your Notes Release 3 applications writen in HiTest to 
Notes Release 4 applications in one of fhree ways, as shown in the following 
figure: 


Notes Release 4 Notes Release 4 


Notes 
Release 3 


Notes 
Release 4 



• You can use fhe original HiTesf code direcfly in Nofes Release 4. 
However, if you do fhis, you cannof use any of fhe Release 4 feafures, 
such as folders. Also, since HiTesf is a 16-bif producf, fhe HiTesf 
application can only work with the 16-bit version of Lofus Nofes 
Release 4. 

• You can convert the HiTest application to an application using Notes 
classes through OLE automation in Visual Basic. This enables you to 
use the Release 4 features. However, some of fhe mefhods and 
properties provided with the Notes classes in LotusScript will not be 
available to you. 

• You can convert to LotusScript. This enables you to use all the Notes 
Release 4 features. 

This chapter covers the above topics in more detail. 
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Creating a Notes Application Using the HiTest Basic API 

The following example shows how to create a new database with a file 
name of TEST.nsf and a title of TEST. 

Example 

1. Create a new form in Visual Basic. 

2. Create a button control for the form and set its caption property to 
CreateDatabase. It looks like this when you are done: 



3. Add the following code to the button's Click Event procedure: 

Dim hgdatabase As Long 
Dim hgstatus As Long 
hgstatus = HTInit (0) 

hgstatus = HTDatabaseCreate("", "TEST.nsf", "TEST", 
"testing", "DISCUSS4.NTF", HTDBCLASS_DB, 0&) 

If hgstatus = 0 Then 

Print "test.nsf has been created on your local server" 
hgstatus = HTTerm(O) 

Eollowing is an explanation of the code. 

We declare an hgdatabase variable that references a Notes database. In 
HiTest, we present a Notes database handle as long. 

.Dim hgdatabase As Long 
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We declare an hgstatus variable. All the status codes we get later will 
be put in the variable. 

Dim hgstatus As Long 

For every HiTest application, we must initialize the Notes session 
as a first step. Other functions can only be called after session 
initialization. If the initialize is imsuccessful, it will return either 
HTFA1L_H1TEST_VERS10N (program built with incompatible HiTest 
API version) or HTEA1L_N0TES_VERS10N (the HiTest API requires 
Notes Release 3.0 or higher) to hgstatus. 
hgstatus = HTInit(0) 

We create a standard Notes database on a local server. The database file 
name is TEST.nsf and its title is TEST. It returns a failure code to 
hgstatus if fhe fimction does not work successfully. 

hgstatus = HTDatabaseCreate ("", "TEST.nsf", "TEST", 
"testing", "DISCUSS4.NTF", HTDBCLASS_DB, 0&) 

If hgsfatus does not contain any failure code, a message is displayed. 

If hgstatus = 0 Then 

Print "test.nsf has been created on your local server" 

We close fhe Nofes session. Each HTInit function must be closed. If 
there is a failure, the same failure code will be refumed as for HTInit. 

hgstatus = HTTerm(O) 

4. Erom the Visual Basic menu, choose Eile-Add Eile to add three modules 
to your project: HTEUNC.BAS, HTNOTES.BAS, HTVISUAL.BAS. They 
contain the HiTest object definitions, HiTest constant definitions, and 
HiTest function definitions. 
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5. Choose Run-Start to run the application. The following form appears: 


kL Formi 


lIslD 


CreateD at abase 


6. Click fhe CreafeDafabase buffon. A message confirming fhe creafion of 
fhe new dafabase displays. 

7. Open fhe Nofes workspace. 

8. Choose File - Dafabase - Open fo add fhe new dafabase called TEST fo 
your workspace. 



start 11 lit Woiksoace at Of... , 11 00 
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Converting a HiTest Application Using Notes Classes in Visual Basic 
through OLE Automation 

Lotus Notes Release 4 is an OLE automation server. Converting your 
HiTest applications to LotusScript Notes classes through OLE automation 
enables you to develop and use your applications in all the environments 
supported by Visual Basic, such as Windows, Windows 95 and Windows 
NT. 

To convert applications developed using the HiTest tools, you translate the 
HiTest Basic API functions to equivalent Lotus Notes functions. There is a 
number of LofusScripf Nofes class mefhods fhaf perform funcfions 
equivalenf fo HiTesf funcfions. 

Note Eor more defails, see Appendix 1. 

By converting your HiTesf applicafions, you can more easily access fhe new 
Release 4 Nofes design elemenfs. Eor example, HiTesf has no supporf for 
accessing fhe currenf Nofes documenf and Nofes ifem. LofusScripf Nofes 
classes, on fhe ofher hand, include NofesUiWorkspace and 
NofesUiDocumenf which enable you fo access fhe currenf Nofes workspace 
and fhe currenf Nofes documenf. You can access fhe currenf Nofes ifem 
using fhe CurrenfEield properfy of NofesUiDocumenf. 

Lef's look af an example. 

Example 

This example shows how you can access fhe currenf Nofes documenf in 
Visual Basic using LofusScripf Nofes classes fhrough OLE aufomafion. You 
will need fo keep bofh Lofus Nofes and fhe currenf documenf open. 
Ofherwise, alfhough fhe application will be able fo open fhe Nofes 
workspace, if will refurn an error message indicafing fhaf if cannof find fhe 
currenf documenf. 

Dim uispace As Object 

Dim uidoc As Object 

Dim doc As Object 

Set uispace = CreateObject("Notes.NotesUIWorkspace") 

Set uidoc = uispace.CurrentDocument 
Set doc = uidoc.Document 
Print (doc.Created) 

Set uispace = Nothing 

To gef fhe Subjecf ifem value of fhe currenf documenf (NofesUiDocumenf), 
we need fo gef fhe hierarchy from fhe currenf workspace 
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(NotesUIWorkspace). We declare uispace as an object which references the 
current workspace. 

Dim uispace As Object 

We declare uidoc as an object which references the current document. 

Dim uidoc As Object 

We declare doc as an object which references the document. 

Dim doc As Object 

We use the CreateObject function in Visual Basic to get the reference to 
NotesUIWorkspace, and store it in uispace. 

Set uispace = CreateObject("Notes.NotesUIWorkspace") 

We get the reference to NotesUiDocument using the CurrentDocument 
property of NotesUIWorkspace. 

Set uidoc = uispace.CurrentDocument 

We get the reference to NotesDocument using the Document property of 
NotesUiDocument. 

Set doc = uidoc.Document 

We print the current document's created data. 

Print (doc.Created) 

We release the references. 

Set uispace = Nothing 

You can use the Notes Release 4 features like folders; however, some 
methods, such as the New method of NotesDatabase, cannot be used here. 
You also cannot use the Forall and Foreach statements when using Notes 
classes through OLE automation in Visual Basic. This is because Visual 
Basic does not know the concept of a collection, which is a LotusScript way 
of accessing elements. 

Let's take a look now at how to convert the Notes HiTest application 
created in the previous section to a Visual Basic application using Notes 
classes through OLE automation in Visual Basic. 

1. Use the Visual Basic form created in the previous section and save it 
using a new name. 
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2. Put the following code on the Create Database button of forml. 

Dim session As Object 
Dim dbl As Object 
Dim db2 As Object 

Set session = CreateObject("Notes.NotesSession") 

Set dbl = session.GetDatabase , "test.nsf") 

Set db2 = dbl.CreateFromTemplate("", "test2.nsf",True) 
Print ("test2.nsf is created on local server") 

Set db2 = Nothing 

Set dbl = Nothing 

Set session = Nothing 

Following is an explanation of fhe code. 

When using Nofes classes in Visual Basic fhrough OLE automation, 
fhere are fwo exfernally creafable objecfs available: NofesSession and 
NofesUlWorkspace. You can gef references to ofher objecfs from fhese 
fwo objecfs. 

We define dbl and db2 as objecfs fhaf reference NofesSession and 
NofesDafabase. When using Nofes classes in Visual Basic, you cannof 
direcfly creafe a dafabase from a femplafe as you cannof use fhe New 
mefhod of fhe NofesDafabase class. Therefore, you need fo gef an 
inherifance from anofher dafabase, dbl, based on fhe DiSCUSS4.NTF 
femplafe. 

Dim session As Object 
Dim dbl As Object 
Dim db2 As Object 

We gef a reference fo NofesSession fhrough CreafeObjecf and sfore if in 
session. We gef a reference fo NofesDafabase using fhe GefDafabase 
mefhod of NofesSession. 

Set session = CreateObject("Notes.NotesSession") 

Set dbl = session.GetDatabase ("", "test.nsf") 

For fhe HTDafabaseCreafe funcfion of fhe HiTesf Visual Basic API, 
fhere is an equivalenf funcfion available in LofusScripf. if is fhe 
CreafeFromTemplafe mefhod of fhe NofesDafabase class. We creafe a 
new dafabase wifh a file name of fesf2.nsf on fhe local server using fhis 
mefhod. The new dafabase inherifs fhe TEST dafabase. 

Set db2 = dbl.CreateFromTemplate("", "test2.nsf", True) 
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We inform the user that the database is created. 

Print ("test2.nsf is created on local server") 

We release the Notes objects. 

Set db2 = Nothing 
Set dbl = Nothing 
Set session = Nothing 

3. Save the new project. 

4. Choose Run-Start from the Visual Basic menu. Forml is displayed. It 
looks like this: 



5. Click the CreateDocument button to run the application. A message 
displays which informs you that test2.nsf has been created on the local 
server. 

6. Switch to Lotus Notes. 

7. Select File - Database - Open and add the new database to your 
workspace. 
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Converting a HiTest Application to LotusScript in Notes 

LotusScript is part of Lotus Notes Release 4. When using LotusScript in 
Notes, you do not need an additional compiler for the language. Lotus 
Notes compiles and runs the code. Converting your application to 
LotusScript in LotusNotes enables you to distribute your applications 
across a wider range of plafforms, such as Windows, OS/2 and UNIX. 

In HiTesf Tools for Visual Basic, you firsf initialize a session object and use 
the hierarchy of fhe session objecf fo access fhe lower level objecfs. 

Using LofusScript Nofes classes through OLE automation in Visual Basic 
you first create one of fhe fwo externally creatable objects: 
NotesUlWorkspace or NotesSession. You access the lower-level objects 
using the methods and properties of fhe higher-level objecfs. 

In Lofus Nofes, when using LofusScript, you can create most of fhe Nofes 
objecfs withouf using the properties or methods of fhe higher-level classes. 
This is an example of how to create a new Notes database: 

Dim db As New NotesDatabase("","discuss4.ntf") 

We want to create a new Notes database directory on a server called Mail: 

Dim dbdir As New NotesDbDirectory("Mail") 

LotusScript also supports the Forall and Foreach statements which are not 
supported in Visual Basic using Notes classes through OLE automation. 

For example, you can access all the views in a database like this: 

Forall view In db.Views 

Messagebox "View name: " & view.Name 
End Forall 

Let's look at how to convert the sample from "Converting a HiTest 
Application Using Notes Classes in Visual Basic through OLE Automation" 
into a LotusScript application which is used directly in LotusNotes. 

1. Open the TEST database in Lotus Notes. 

2. Choose Create - Agent from the menu to create a new agent. 

3. Enter the title of fhe agent in the Name field. 
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4. Under When should this agent run?, select Manually From Actions 
Menu. 



5. In the Event: box, choose Initialize as the event to drive the script. 
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6. Enter the following code on the edit pane: 

Sub Initialize 

Dim session As New NotesSession 
Dim dbl As NotesDatabase 
Dim db2 As NotesDatabase 

Set dbl = session.GetDatabase, "test.nsf") 

Set db2 = dbl.CreateFromTemplate("", 

"tests.nsf",True) 

Messagebox ("tests.nsf is created on local server") 
End Sub 

Following is an explanation of fhe code. 

This code is quife similar fo fhe one we used in Visual Basic using OLE 
aufomafion. However, rafher fhan declaring fhe Nofes objecfs as 
objecfs, we declare fhem as LofusScripf Nofes classes. Also, we declare 
fhe session as NofesSession. 

Dim session As New NotesSession 

We declare dbl as NofesDafabase which references fhe TEST dafabase. 

Dim dbl As NotesDatabase 

We declare db2 as NofesDafabase which will be fhe new dafabase and 
is inherifed from fhe TEST dafabase. 

Dim db2 As NotesDatabase 

We use fhe mefhods of LofusScripf Nofes classes fo creafe fhe new 
dafabase, jusf as we did in Visual Basic using OLE aufomafion. 

Set dbl = session.GetDatabase ("", "test.nsf") 

Set db2 = dbl.CreateFromTemplate("", "tests.nsf", True) 

We inform fhe user fhaf dafabase fesfS.nsf is creafed. 

Messagebox ("tests.nsf is created on local server") 
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As we can use the New method of NotesDatabase to create a database 
from a femplafe, we can create this much simpler program which 
performs fhe same funcfion: 

Sub Initialize 

Dim db As New NotesDatabase"DISCUSS4.NTF") 

Call db.CreateFromTemplate("", "tests.nsf" ,True) 
Messagebox db.Title 
End Sub 

Following is an explanation of fhe code: 

We declare db as a new dafabase fhat inherits the D1SCUSS4.NTF 
template. 

Dim db As New NotesDatabase"DISCUSS4.NTF") 

We call the CreateFromTemplate method of NofesDatabase fo create 
and initialize the database. 

Call db.CreateFromTemplate, "tests.nsf" ,True) 

We put the title of fhe database on the message box. 

Messagebox db.Title 

7. Save and close the agent by choosing File - Close from the Notes menu. 

8. On the Notes workspace, select the TEST database. 

9. Choose Agent - Create Database from the Notes menu to run the agent. 
A message displays informing you thaf fhe dafabase is creafed. 
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10. From the Notes menu, choose File - Database - Open to add the new 
database to the workspace. 



The following chapters discuss how to access the following major Nofes 
elemenfs: NofesSession, Nofes Dafabase, Nofes Document, Notes View, 
and Notes Item. We will look at how to access those elements using the 
HiTest Basic API, using Notes classes in Visual Basic through OLE 
automation, and using LotusScript in Notes. 
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Chapter 6 

Accessing Notes Sessions 


Notes sessions provide access to environment variables and address books, 
and they provide information on the current user. Notes platform and 
Nofes release number. 

In fhis chapfer, we will discuss how fo access Nofes sessions: 

• In HiTesf 

• Using Nofes classes fhrough OLE aufomafion in Visual Basic 

• Using LofusScripf in Nofes. 


Accessing Notes Sessions Using the HiTest Basic API 

Session class funcfions are global wifhin a HiTesf API session (one 
processor fask). These funcfions have no confexf beneafh fhe implicif 
session confexf — fhaf is, no funcfions in ofher classes affecf fheir 
operafion — and fhey are always usable, affer calling HTlnif. 

Every HiTesf API program musf inifialize and ferminafe fhe HiTesf API. 
Unless you call fhe HiTesf API inifializafion funcfion HTlnif fo esfablish a 
session, all ofher funcfions will fail. Addifionally, every HiTesf API 
program musf call fhe HTTerm funcfion affer all HiTesf API funcfion calls 
are complefe and before fhe program ferminafes. If is crucial fo call fhe 
ferminafion funcfion fo avoid leaving fhe sysfem in a dangerous sfafe. 

The single excepfion fo fhese resfricfions is fhe HTGefAPlLibraryVersion 
funcfion, which may be used before inifializafion fo check fhe HiTesf 
API DLL version code and sfring. The version of fhe HiTesf API wifh 
which a program was creafed can be obfained wifh fhe consfanfs 
HTVERS10N_L1BRARY for fhe version code and 
HTVERS10N_L1BRARY_STR1NG for fhe version sfring. 

Por defailed informafion on fhe Nofes session funcfions, refer fo fhe online 
help informafion for fhe HiTesf Tools Visual Basic API. 

Lef's look af some of fhe funcfions. 
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Accessing Notes Session Properties 

HTGetProperty fetches one of various session-level property values into a 
supplied buffer. Each property has a data t 5 ^e, and the buffer must be large 
enough to hold the result. 

HTSetProperty assigns a value to a session-level property. The t 5 ^e of the 
data is indicated by the property. When setting the value of properties 
which are inherited by newly opened databases, the new value has no effect 
on currently open databases. 

Let's look at an example. 

Example 

This example retrieves and prints a session property for the current user's 
name. 

Dim hgstatus As Long 
Dim hgvalue As String 

hgvalue = String(HTMaxLen_User_Name, 0) 
hgstatus = HTInit(O) 

hgstatus = HTGetProperty(HTSession_User_Name, ByVal hgvalue) 
hgvalue = Left(hgvalue, InStr(hgvalue, Chr$(0)) - 1) 

If hgstatus = 0 Then Print "The current user is " & hgvalue & 

II II 

hgstatus = HTTerm(O) 

Following is an explanation of fhe code. 

We declare an hgsfafus variable. All the status codes we get later will be 
put in the variable. 

Dim hgstatus As Long 

We declare hgvalue as a string which will store the user name of fhe Nofes 
session. 

Dim hgvalue As String 
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For every HiTest application, we must initialize the Notes session as a first 
step. Other fimctions can only be called after session initialization, if the 
initialize is unsuccessful, if will refurn eifher HTFAiL_HiTEST_VERSiON 
(program builf with incompatible HiTest API version) or 
HTEAiL_NOTES_VERSiON (the HiTest API requires Notes Release 3.0 or 
higher) to hgstatus. 

hgstatus = HTInit(O) 

We set the string length as the maximum length of fhe user name in Nofes. 
HTMaxLen_User_Name is a consfant defined by HiTesf fo present the 
maximum length of fhe Nofes user name. 

hgvalue = String(HTMaxLen_User_Name, 0) 

We gef fhe user name and sfore if in hgvalue. 

hgstatus = HTGetProperty(HTSession_User_Name, ByVal hgvalue) 

We sef fhe sfring to only contain valid characters. 

hgvalue = Left(hgvalue, InStr(hgvalue, Chr$(0)) - 1) 

We print out the user name. 

If hgstatus = 0 Then Print "The current user is " & hgvalue & 

II II 

We close the Notes session. Each HTinit function must be closed, if fhere is 
a failure, fhe same failure code will be refurned as for HTinit. 

hgstatus = HTTerm(O) 

Accessing Notes Session Environment Vaiues 

HTGetEnvironmentString retrieves the value of a Nofes environment string 
variable. Notes stores environment variables in the NOTES.iNi file. Use fhe 
HTSefEnvironmentSfring function to modify Nofes environment variables. 
To retrieve import/ export formats, which are stored in multiple 
environment variables, use the functions HTCompositeListimport and 
HTCompositeListExport. 

HTSetEnvironmentString assigns a value to a Notes environment string 
variable. The calling program controls whether to create a new environment 
variable. Notes stores environment variables in the NOTES.iNi file. Use fhe 
HTGefEnvironmentSfring function to retrieve Notes environment variables. 
Use care when modifying Nofes environment variables, since they affect the 
Notes client and server programs. 

Let's look at an example. 
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Example 

This example sets the value of a Notes environment variable in the 
NOTES.INI. If fhe variable does nof already exisf, if is creafed. 

Dim hgstatus As Long 


hgstatus = HTInit(O) 

hgstatus = HTSetEnvironmentString("TestOfAPI", "It worked", 
HTSetEnvF_Create) 

If hgstatus = 0 Then Print "This environment variable has 
been set in your notes.ini file." 

hgstatus = HTTerm(O) 

Following is an explanation of fhe code. 

We sef fhe environment TestOfAPI to "It worked". If fhe TesfOfAPl does 
nof already exisf in NOTES.INI, we creafe if. If if fails, an error code is 
refurned: "Value is longer than the maximum environment string length". 

hgstatus = HTSetEnvironmentString("TestOfAPI", "It worked", 
HTSetEnvF_Create) 

If fhe seffing is successful, we print out a message to inform the user. 

If hgstatus = 0 Then Print "This environment variable has 
been set in your notes.ini file." 


Accessing Notes Sessions in Visuai Basic Using Notes Ciasses through 
OLE Automation 

Using Notes classes through OLE Automation in Visual Basic, we present 
the session as NotesSession. The NotesSession class provides a means for 
accessing affribufes of fhe user environment and information about agents. 
It also provides methods for accessing environment variables. 

Following is a table which converts the HiTest Basic API functions 
accessing Notes sessions to the equivalent functions and properties using 
Notes classes through OLE Automation: 
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HiTest Functions 

Notes Class methods and Properties 

Summary 

HTConvert 


Converts data between data types. 

HTConvertGetLength 


Returns the length of data converted as 
indicated. 

HTGetAPILibraryVersion 


Obtains the HiTest API DLL version 

information. 

HTGetEnvironmentString 

GetEnvironmentString 

Obtains the value of a Notes environment 
string variable. 

HTGetFormat 


Obtains the default formatting configuration. 

HTGetInternational 

International 

Obtains the international configuration 
information. 

HTGetProperty 

UserName, CommonUserName, 
IsOnServer, NotesVersion, (only in 
Release 4.5: International, GetAgent) 

Obtains a session-level property value. 

HTInit 

CreateObject 

Initializes the HiTest API. 

HTSetEnvironmentString 

SetEnvironmentV ar 

Assigns the value of a Notes environment 
string variable. 

HTSetFormat 


Assigns the default formatting configuration. 

HTSetInternational 


Assigns the international configuration 
information. 

HTSetProperty 


Assigns the value of a session-level property. 

HTStringFetch 


Fetches string from within an HT structure. 

HTTerm 

Close 


HTTranslate 


Translates a string between the native 
character set and LMBCS. 


Platform 

Name of the OS Platform 


CurrentDatabase 

Object Reference to the database in which the 
Agent lives 


CurrentAgent 

Object reference to the current agent 
program 


EffectiveUserName 

Name of the person who created the agent 


SavedData 

Handle to document that stores persistent 
agent data 


AddressBooks 

Returns array containing database objects for 
known address books. 


UpdateProcessedDoc 

Records document processed by agent. 


Continued 
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HiTest Functions 

Notes Class methods and Properties 

Summary 


GetDatabase 

Equivalent to New Notes Database (see 
HiTest Database Object) 


CreateDateTime 

Equivalent to New NotesDateTime 


CreateLog 

Create Log (Equivalent to New NotesLog) 


CreateN ewsletter 

Equivalent to New NotesNewsletter 


GetDbDirectory 

Equivalent to New NotesDbDirectory 


GetEnvironmentValue 

Retrieves a numeric environment value. 


Note The International method will be available in Lotus Notes 
Release 4.5. 

Accessing Notes Session Properties 

Using the object.property syntax, you can access all the session properties. 
Let's look at an example: 

Example 

Dim session As Object 

Set session = CreateObject ("Notes.NotesSession") 

Print ( session.UserName ) 

Set session = Nothing 

Following is an explanation of the code. 

We declare session as an object which will reference fhe NofesSession class. 

Dim session As Object 

We gef a reference fo NofesSession using CreateObjecf. 

Set session = CreateObject ("Notes.NotesSession") 

We display fhe current user name. 

Print ( session.UserName ) 

We release the NotesSession object. 

Set session = Nothing 
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Accessing Notes Session Environment Vaiues 

Using GetEnvironmentString, SetEnvironmentVar and 
GetEnvironmentValue, we can access Notes session environment values. 

The GetEnvironmentValue, GetEnvironmentString, and SetEnvironmentVar 
methods retrieve and set environment variables, which are stored in the 
local NOTES.lNl or Preferences file. Use GefEnvironmentValue only for 
numeric environment variables. Use GetEnvironmentString for sfrings and 
numeric values. 

SefEnvironmentVar prepends a dollar sign ($) to argument 1, the name of 
the environment variable. This forces a disfincfion befween user 
environment variables (name starts with a dollar sign) and system 
environment variables (name does not start with a dollar sign). 
GetEnvironmentValue and GetEnvironmentString prepend a dollar sign if 
fhe second argument is false or omitted, and do nof prepend a dollar sign if 
fhe second argument is true. This permits you to examine system 
environment variables as well as user ones. 

Environment variables are useful for saving sfafe and data between Notes 
sessions on a single server or workstations where no conflicts are possible. 
They are also useful for obfaining the environment information set by 
Notes, such as KitType, Directory, Preferences, Domain, Port, and so on. 

Let's look at an example. 

Example 

The following example shows how to set a Notes environment value in 
NOTES.lNl. 

Dim session As Object 

Set session = CreateObject("notes.notessession") 

Call session.SetEnvironmentVar("TestOfAPI", "IT WORKS") 

Set session = Nothing 

Eollowing is an explanation of fhe code. 

We use fhe SefEnvironmentVar method of SessionObjecf fo sef fhe 
environment variable. 

Call session.SetEnvironmentVar("TestOfAPI", "IT WORKS") 
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Accessing Notes Sessions in LotusScript 

When we use LotusScript in Notes, we have only one Notes session; so 
successive calls to the New method return the same session handle. You do 
not need the session handle to access databases or perform other operations 
in LotusScript. It is only used to access the session properties, methods and 
Notes session environment values. 

You can close a session at any time with the Close method. The Close 
method is implicit upon program termination. 

For detailed information on NotesSession, refer fo Chapfer 3. 

Example 

This buffon example incremenfs fhe environmenf variable $SeqNo by one 
and prinfs fhe resulf. (This scripf would nof be reliable on a server for 
mainfaining a sysfem of sequential numbers.) 

Sub Click(Source As Button) 

Dim session As New NotesSession 

Dim seqNo As integer 

segNo = session.GetEnvironmentValue("SeqNo") 

If Isempty(seqNo) Then 

Call session.SetEnvironmentVar("SeqNo", 1) 

Else 

seqNo = seqNo + 1 

Call session.SetEnvironmentVar _ 

("SeqNo", Cint(seqNo)) 

End If 

Messagebox session.GetEnvironmentValue("SeqNo") 

Call session.Close 
End Sub 

Following is an explanation of fhe code: 

We declare session as a new Nofes session objecf. 

Dim session As New NotesSession 

We declare seqNo as an infeger which references fhe Environmenf value. 

Dim seqNo As integer 
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We get the Environment value in NOTES.INI and store it in seqNo. 

seqNo = session.GetEnvironmentValue("SeqNo") 

If there is no seqNo in NOTES.INI, we create it and set it to 1, otherwise we 
increase the Environment value by one. 

If Isempty(seqNo) Then 

Call session.SetEnvironmentVar("SeqNo", 1) 

Else 

seqNo = seqNo + 1 

Call session.SetEnvironmentVar _ 

("SeqNo", Cint(seqNo)) 

End If 

We print out the Environment value. 

Messagebox session.GetEnvironmentValue("SeqNo") 

We close the Notes session using the Close method. 

Call session.Close 
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Chapter 7 

Accessing Notes Databases 


A database is a file used by Notes to store data in the form of documents. A 
database also contains metadata in the form of forms, views, agents, and an 
Access Control List (ACL). 

In this chapter, we will discuss how to access a Notes database 

• In HiTest 

• Using Notes classes through OLE automation in Visual Basic 

• Using LotusScript in Notes. 


Accessing Notes Databases Using the HiTest Basic API 

In the HiTest Visual Basic API, the database object exists in the implicit 
context of the session and represents Lotus Notes databases as distinct 
objects. The primary attributes of a database are the server name, database 
name, database file path (relative to the Notes data directory), and a handle 
when the database is opened. 

A database may be opened, in which case it is represented by a handle. 
When opened, the contents of a database are accessed and manipulated 
with this handle. An open database also contains status information 
pertaining to the database file. Many of the remaining objects exist within 
the context of a database. Some objects use a database directly and some 
indirectly through a document, which is only valid in the context of that 
database, including indices, open documents, metadata, and properties. 
Multiple databases may be opened in a single session. The HiTest API uses 
the global constant NULLHANDLE = 0 to represent an invalid database 
handle. 

Accessing Notes Database Properties 

HTDatabaseGetProperty : Eetches one of various database-level property 
values into a supplied buffer. Each property has a data t 5 ^e, and the buffer 
must be large enough to hold the result. 
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HTDatabaseSetProperty : Assigns a value to a database-level property. 
The type of the data is indicated by the property. When setting the value of 
properties, which are inherited by open indices, the new value has no effect 
on currently open indices. 

Example 

The following example sefs fhe fifle of fhe database. 

Dim hgdatabase As Long 
Dim hgstatus As Long 


hgstatus = HTInit(O) 

hgstatus = HTDatabaseOpen ("", "test.nsf", 0&, hgdatabase) 

hgstatus = HTDatabaseSetProperty(hgdatabase, 

HTDATABASE_TITLE, ByVal "New Title") 

hgstatus = HTDatabaseClose(hgdatabase, HTDBCLOSEF_SAVE_DOCS) 
hgstatus = HTTerm(O) 

Following is an explanation of fhe code: 

We declare an hgdafabase variable fhaf references a Nofes dafabase. In 
HiTesf, we present a Notes database handle as long. 

Dim hgdatabase As Long 

We declare an hgstatus variable. All the status codes we get later will be 
put in the variable. 

Dim hgstatus As Long 

For every HiTest application, we must initialize the Notes session as a first 
step. Other functions can only be called after session initialization. If the 
initialize is unsuccessful, if will refurn eifher HTFA1L_H1TEST_VERS10N 
(program built with incompatible HiTest API version) or 
HTEA1L_N0TES_VERS10N (the HiTest API requires Notes Release 3.0 or 
higher) to hgstatus. 

hgstatus = HTInit(O) 

We open the TEST database, which is already on the local server. This 
returns a database handle, a long value to the hgdatabase variable. 0& 
refers fo fhe dbopen flag. If the database cannot open, a failure nofification 
(database does not exist) will be returned to hgstatus. 

hgstatus = HTDatabaseOpen ("", "test.nsf", 0&, hgdatabase) 


124 LotusScript for Visual Basic Programmers 



We set the property of hgdatabase. It sets the database title property as 
"New Title". HTDATABASE_TITLE specifies fhe dafabase property to be 
set. If if fails, fhe function will refurn a failure code fo hgsfatus. 

hgstatus = HTDatabaseSetProperty(hgdatabase, 

HTDATABASE_TITLE, ByVal "New Title") 

We open the database specified by hgdafabase. The flag 
HTDBCL0SEE_SAVE_D0CS is a consfant defined by fhe HiTesf API. It 
means that the document has changed but is still open and will be closed 
when the database is closed. If if cannof complefe successfully, fhe funcfion 
will refurn a failure code (unvalid dafabase) fo hgsfafus. 

hgstatus = HTDatabaseClose(hgdatabase, HTDBCLOSEF_SAVE_DOCS) 

We close fhe Nofes session. Each HTInit funcfion musf be closed. If fhere is 
a failure, fhe same failure code will be refurned as for HTInit. 

hgstatus = HTTerm(O) 

Opening and Closing a Database 

The HTDatabaseOpen function opens a Notes database and returns the 
handle. The handle represents an active connection to the indicated 
database file. Multiple dafabases may be open af one time, including 
mulfiple connecfions fo a single dafabase. Access fo fhe dafabase's dafa and 
mefadafa can only occur in the context of an open dafabase. 

Eor more information, refer to the example on how to access Notes 
database properties further on in this chapter. 

Creating a Notes Database 

The HTDatabaseCreate function creates a new database. The database may 
be created from scrafch or from an exisfing dafabase femplafe. The local 
Nofes user will be added fo fhe new dafabase Access Control List (ACL) as 
the manager. 

Eor more information, refer to the example in Chapter 5 on how to create a 
new database called TEST in HiTest. 
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Accessing Notes Databases in Visuai Basic Using Notes Ciasses through 
OLE Automation 

Lotus Notes provides the NotesDatabase and NotesDbDirectory classes to 
access Notes databases. The NotesDatabase and NotesDbDirectory classes 
provide a means for locating and opening Notes databases. NotesDatabase 
provides access to the NotesView, DocumentCollection, and 
NotesDocument objects. NotesDocument can be accessed directly through 
NotesDatabase, or by first obtaining a NotesDocumentCollection or 
NotesView object. 

To convert the HiTest Visual Basic API applications, we translate the 
functions to Notes class methods and properties. Following is a table which 
converts the HiTest Basic API functions accessing the Database class to the 
equivalent functions and properties in the Notes classes: 


HiTest Name 

LotusScript 

Notes Class 

Notes Class Methods or 
Properties 

Summary 

HTDatabaseClose 

NotesDatabase 

Close 

Closes an open database. 

HTDatabaseCompact 

NotesDatabase 

Compact 

Compacts a database file. 

HTDatabaseCopy 

NotesDatabase 

CreateCopy, 

CreateReplica 

Copies part or all of one 
database to another database. 

HTDatabaseCreate 

NotesDatabase 

New, Create, 
CreateFromT emplate 

Creates a new database. 

HTDatabaseCreateFT 

_Index 

NotesDatabase 

UpdateFTIndex 

Full text indexes a local 
database. 

HTDatabaseDelete 

NotesDatabase 

Remove 

Deletes a database file. 

HTDatabaseDeleteFT 

_Index 



Deletes the full text index for 
a database. 

HTDatabaseGetProperty 

NotesDatabase 

IsFTIndexed, Created, 
LastFTIndexed, 

T emplateN ame, 
DesignTemplateName, 
FileName, FilePath, 
LastModified, 

ReplicalD, Server, Size, 
PercentUsed, Title, 
Categories 

Obtains the value of a 
database property. 


Continued 
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HiTest Name 

LotusScript 

Notes Class 

Notes Class Methods or 
Properties 

Summary 

HTDatabaseList 

HTDatabaseListCatalog 

DbDirectory 

GetFirstDatabase, 

GetNextDatabase 

Iterates through Notes 
databases and directories on a 
given server. 

Iterates through databases in a 
database catalog. 

HTDatabaseLocateBy 

_Replicaid 

NotesDatabase 

OpenByReplicalD 

Obtains a database filename 
from a database replica ID. 

HTDatabaseLocateBy 

_Title 

NotesSession 

GetDatabase 

Obtains a database filename 
from a database title. 

HTDatabaseOpen 

Session 

DBDirectory 

Open, GetDatabase 

GetFirstDatabase 

GetNextDatabase 

GetLastDatabase 

GetPreDatabase 

Opens a Notes database. 

HTDatabaseSetProperty 

NotesDatabase 

Title, Categories, 
IsOpen, Managers, 
Views, Agents, Parent, 
ACL, FTSearch, 
Replicate 

Assigns the value of a 
database property. 


Note The New and open methods can only be used in LotusScript. 

Note For the GetFirstDatabase method, you must use the Type number in 
Visual Basic rather than the T 5 ^e constant in LotusScript. 


Type Constant 

Type Number 

DATABASE 

1247 

TEMPLATE 

1248 

REPLICA _CANDIDATE 

1245 

TEMPLATE_CANDIDATE 

1246 


Accessing Notes Database Properties 

We access Notes Database properties in Visual Basic by using the 
NotesDatabase class properties. The database must be open when accessing 
the database properties. Let's look at an example. 

Example 

The following example shows you how to access the database properties. 

Dim session As Object 
Dim db As Object 
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Set session = CreateObject ("Notes.NotesSession") 

Set db = session.GetDatabase ("","test.nsf") 
db.Title = " New Title" 

Set db = Nothing 

Set session = Nothing 

Following is an explanation of the code: 

We declare the session as an object which references the Notes Session 
object. We declare db as an object which references the Notes Database 
object. 

Dim session As Object 

Dim db As Object 

We get a reference to NotesSession. 

Set session = CreateObject ("NotesSession") 

We open the TEST database using the GetDatabase method of 
NotesSession. 

Set db = session.GetDatabase ("","test.nsf") 

We set the Title property of NotesDatabase to "New Title", 
db.Title = " New Title" 

We release the Notes objects. 

Set db = Nothing 
Set session = Nothing 

Opening and Closing a Database 

To open a database we use the GetFirstDatabase or GetNextDatabase 
method of NotesDbDirectory. 

We use the OpenByReplicaiD method to open a database whose server and 
replica ID are known. We can obtain the replica ID from a database that is 
already open using the ReplicaiD property. 

The OpenifModified method opens a database only if it was modified after 
a specified date. 

The OpenMail method opens the user's mail database. 

The Glose method explicitly closes a database. Exiting from Notes implicitly 
closes all open databases. We open a Notes database using the Open 
method of NotesDatabase. We close a Notes database using the Glose 
method of NotesDatabase. 
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All of the methods mentioned above can be used in Visual Basic. 

For the HiTest function, HTDatabaseOpen, the GetDatabase method of 
NotesSession is available, which opens a database specified by the server 
and the database file. 

For the HiTest function, HTDatabaseClose, the Close method of 
NotesDatabase is available, which closes the particular database. 

Let's look at an example. 

Example 

Dim session As Object 
Dim db As Object 

Set session = CreateObject ("NotesSession") 

Set db = session.GetDatabase ("","test.nsf") 

If db.Isopen 

print ( "Database TEST is open") 

End IF 
db.close 

Print (" Database TEST is Closed .") 

Set db = Nothing 
Set session = Nothing 

Following is an explanation of the code: 

We open the test.nsf database on the local server. 

Set db = session.GetDatabase ("","test.nsf") 

We check if the database is open, if it is, we print the message "Database 
TEST is open". 

If db.Isopen 

print ( "Database TEST is open") 

End IF 

We close the database using the Close method. 

db.close 

We print the message that the database is closed. 

Print (" Database TEST is Closed .") 
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Creating a Notes Database 

Create: Creates an uninitialized database. A script can access it, but a user 
cannot access it from the Notes workspace because it has no forms or 
views. 

CreafeFromTemplafe: Creafes an initialized dafabase based on an existing 
femplafe. This dafabase has fhe design of fhe femplafe and can be accessed 
from fhe Nofes workspace. 

CreafeReplica: Creafes an uninitialized replica of an exisfing dafabase. The 
replica musf be inifialized eifher by fhe application developer using fhe 
Replicafe mefhod or by fhe user accessing if from fhe Nofes workspace 
upon firsf use. 

CreafeCopy: Creafes a copy of fhe design of an exisfing dafabase. 

For more defails, refer fo Chapfer 5 which confains an example on how fo 
converf an application using LofusScripf Nofes classes. 


Accessing Notes Databases in LotusScript 

The following describes how fo access Nofes dafabases using LofusScripf in 
Nofes. 

Accessing Notes Database Properties 

You can access Nofes dafabase properfies of an open Nofes dafabase. Using 
LofusScripf direcfly in Lofus Nofes enables you fo use fhe Forall and 
Foreach sfafemenfs, which make if easier fo access fhe properfies. This is 
nof possible in Visual Basic using Nofes classes fhrough OLE aufomafion, 
as Visual Basic does nof know fhe concepf of a collecfion, whereas 
LofusScripf does. 

Lef's look af an example. 

Example 

This example prinfs fhe name of each view in fhe dafabase. A NofesView 
objecf is defined and sef fo each value in fhe Views properfy. The name is a 
properfy of fhe view objecf. You can puf fhe code on an agenf and choose 
inifialize as fhe evenf fo drive fhe agenf. 

Sub Initialize 

Dim session As New NotesSession 

Dim db As NotesDatabase 

Set db = session.CurrentDatabase 
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REM view becomes a NotesView object 
Forall view In db.Views 

Messagebox "View name: " & view.Name 
End Forall 
End Sub 

Following is an explanation of the code. 

We will process a view whose object class is NotesView. it descends from 
NotesDatabase, which in turn descends from NotesSession. So in this 
statement we declare a NotesSession with a property of CurrentDatabase 
that allows us to access the current database. 

Dim session As New NotesSession 

We declare db to reference the current database. 

Dim db As NotesDatabase 

We get the reference to the current database using the CurrentDatabase 
method of session, and store it in the db variable. 

Set db = session.CurrentDatabase 

We include a comment to state that the view is a NotesView object in our 
case. The LotusScript compiler will ignore this statement. 

REM view becomes a NotesView object 

We process all the views in the database and display all the views' names 
one by one in a message box. 

Forall view In db.Views 

Messagebox "View name: " & view.Name 

End Forall 

Opening and Closing a Database 

You can use the New method of NotesDatabase in LotusScript. The New 
method opens an existing database. The first argument specifies the server 
and defaults (empty string) to the local Notes directory. The second 
argument specifies the file name of the database, if you specify an empty 
string here, you must later use the Open method to open the database. 

if you are running on a server and want to open a database on that server, 
specify the first argument as an empty string. The New method does not 
create a database. 
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Let's look at an example: 

Example 

Dim db As New NotesDatabase( "", "" ) 

Call db.Open( "HongKong", "sales.nsf" ) 

Following is an explanation of the code. 

We create a NotesDatabase object which does not reference any objecf yef, 
and will open it later on. 

Dim db As New NotesDatabase( "", "" ) 

We open the sales .nsf database on the HongKong server, and have db 
reference fhe sales.nsf dafabase on the HongKong server. 

Call db.Open( "HongKong", "sales.nsf" ) 

Creating a Notes Database 

Use one of fhe following mefhods of NofesDafabase fo creafe a dafabase: 
Creafe, CreafeFromTemplafe, CreafeReplica, CreateCopy. 

Note The New mefhod does nof creafe a database. 

Example 

The following example creafes a local dafabase named saledisc.nsf based on 
fhe Nofes femplafe discussT.ntf and changes fhe fifle. The dafabase objecf 
for the template is discuss and the database object for the new database is 
db. The third argument, CreateFromTemplate, inherits design changes. Put 
the code on an agent and choose initialize to drive the script. 

Sub INITIALIZE 

Dim discuss As New NotesDatabase, "DISCUSS4.NTF") 

Dim db As NotesDatabase 

Set db = discuss.CreateFromTemplate_ 

("", "SALEDISC", True) 

db.Title = "Sales Discussion Database" 

End Sub 

Following is an explanation of fhe code. 

We declare fwo dafabases: db and discuss. 

Dim discuss As New NotesDatabase, "DISCUSS4.NTF") 

Dim db As NotesDatabase 
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We create a new database on a local server. The file name of fhe dafabase is 
SALEDISC and it uses discuss as the database template. 

Set db = discuss.CreateFromTemplate_ 

"SALEDISC", True) 

We set the new database db's title property to "Sales Discussion Database". 

db.Title = "Sales Discussion Database" 

Note in Lotus Notes Release 4.5, a new front-end class will be available, 
NotesUlDatabase. This class can only be used in LotusScript, in an opened 
database, you can use it to access the current database using scripts. 
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Chapter 8 

Accessing Notes Views 


A view is one of two primary types of metadata. The other is a form. Each 
database contains one or more views, which describe one representation of 
some or all of the documents in a database. A view consists of various 
attributes and one or more columns. In addition, each view defines a 
collection. A views collection is a hierarchical, sorted collection of 
documents, categories, and totals. 

In this chapter, we will discuss how to: 

• Access Notes views in HiTest 

• Access Notes views and folders using Notes classes through OLE 
automation in Visual Basic 

• Access Notes views and folders using LotusScript in Notes. 

Note Eolders are new in Notes Release 4. 


Accessing Notes Views Using the HiTest Basic API 

Lotus Notes internally represents views as data. The HiTest API view 
abstraction represents views as metadata, and supports easy access to that 
metadata. The primary attributes of a view are a name and an ID. The 
HiTest API uses the global constant NULLID = 0 to represent an invalid 
view ID. 

Accessing Notes View Attributes 

HTViewPetch fxmction: Petches the attributes of a particular view. It returns 
an hgview t 5 ^e value which contains the attributes. 

Let's look at an example. 

Example 

Locates a view, retrieves the attributes of that view, and prints the name 
attribute. 

Dim hgstatus As Long 
Dim hgdatabase As Long 
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Dim hgviewid As Long 
Dim hgview As HTView 
Dim temp As String 

hgstatus = HTInit(O) 

hgstatus = HTDatabaseOpen ("", "htvb20.nsf", 0&, hgdatabase) 

hgviewid = HTViewLocateByName(hgdatabase, "HiTest API - All 
Documents") 

hgstatus = HTViewFetch(hgdatabase, hgviewid, hgview) 

If hgstatus = 0 Then 

temp = Left(hgview.hgname, InStr(hgview.hgname, Chr$(0)) 

- 1 ) 

Print "The view name is '" & temp & ">." 

End If 

hgstatus = HTDatabaseClose(hgdatabase, 0&) 
hgstatus = HTTerm(O) 

Following is an explanation of the code. 

To locate the view, we need to know the view id of the particular view, in 
HiTest, the Notes view id is presented as long. This statement declares a 
view id. 

Dim hgviewid As Long 

This statement declares a variable which references the Notes view. 

Dim hgview As HTView 

We declare a string variable which will contain the view's name later. 

Dim temp As String 

We put the Notes view id in hgdatabase in hgviewid. The view is specified 
by the view name "HiTest API - ALL Documents", if no view exists, it will 
return NULLiD. 

hgviewid = HTViewLocateByName(hgdatabase, "HiTest API - All 
Documents") 

We fetch a Notes view in hgdatabase. The view is specified by hgviewid. if 
it fails, a failure code of invalid database or view is returned to hgstatus. 

hgstatus = HTViewFetch(hgdatabase, hgviewid, hgview) 
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If there is no error code returned by HTViewFetch, we get and print the 
view's name. 

If hgstatus = 0 Then 

temp = Left(hgview.hgname, InStr(hgview.hgname, Chr$(0)) 

- 1 ) 

Print "The view name is '" & temp & ">." 

End If 

Locating a View 

Use the HTViewLocateByName function in HiTest to obtain the view ID of 
a view through the use of that view's name. 

Refer to our previous example of fetching Notes view attributes. 

Deieting a View 

The HTViewDelete Function deletes a view from a database. 

Note A view currently used as the active view in an index cannot be 
deleted. 

Let's look at an example. 

Example 

This Visual Basic code deletes a view from a database. This is not a working 
example because a valid view needs to be supplied first. 

Dim hgstatus As Long 

Dim hgdatabase As Long 

Dim hgviewid As Long 

hgstatus = HTInit(O) 

hgstatus = HTDatabaseOpen ("", "test.nsf", 0&, hgdatabase) 

hgviewid = HTViewLocateByName(hgdatabase, "HiTest API - All 
Documents") 

hgstatus = HTViewDelete(hgdatabase, hgviewid) 

If hgstatus = 0 Then Print "The view has been deleted." 
hgstatus = HTDatabaseClose(hgdatabase, 0&) 
hgstatus = HTTerm(O) 
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Following is an explanation of the code: 

We delete a view in the database specified by hgdatabase. The view is 
specified by hgviewid. if it cannot run successfully, an error code is 
returned. 

hgstatus = HTViewDelete(hgdatabase, hgviewid) 

if the view is deleted successfully, a message displays saying that the view 
has been deleted. 

If hgstatus = 0 Then Print "The view has been deleted." 

Other Functions in HiTest for Working with Views 

HTViewCopy: Copies a view from one database to another. 

HTViewList: iterates through views in a database. 

HTViewcellFetch: Converts and retrieves the data for a viewcell into a 
supplied buffer. 

HTViewcellGetLength: Obtains the length of a viewcell as converted to a 
specified data t 5 ^e. 


Accessing Notes Views and Folders in Visual Basic Using Notes Classes 
through OLE Automation 

We translate the HiTest view functions to equivalent methods and 
properties using Notes classes. The NotesView class lets you locate 
documents within views and folders, and perform operations on views 
and folders. 

Following is a table which converts the HiTest Basic API functions to the 
equivalent functions and properties using Notes classes: 

HiTest Function Name Notes Classes Notes Classes Summary 

Methods and 
Properties 

HTViewCopy 

HTViewDelete NotesView Remove 

HTViewList 

HTViewLocateByName NotesDatabase GetView, New 

Continued 


Copies a view from one database to 
another. 

Deletes a view from a database. 
Iterates through views in a database. 

Obtains a view ID from the view 
name. 
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HiTest Function Name 

Notes Classes 

Notes Classes 
Methods and 
Properties 

Summary 

HTViewFetch 

NotesView 

Created 

The date the view was created. 


NotesView 

LastModified 

The date the view was last modified. 


NotesView 

UniversallD 

The UNID of the View. 


NotesView 

Parent 

A reference to the database object 
which owns this view. 


NotesView 

IsDefaultView 

True if the view is the default view 
for the database. 


NotesView 

IsFolder 

True if the object represents a folder. 

HTViewcellFetch 

NotesView 

Columns 

Converts and retrieves the data for a 
viewcell into a supplied buffer. 

FITViewcellGetLength 



Obtains the length of a viewcell as 
converted to a specified data type. 


Note The New method is a new feature in Notes Release 4.5 and can only 
be used in LotusScript. 

Note Folders are new in Notes Release 4. They are not supported by the 
HiTest Visual Basic API. When you use Notes classes in Visual Basic 
through OLE automation and in LotusScript in Notes Release 4, you can 
access folders in your application. 

Accessing Notes View Properties 

You can access Notes view properties using the NotesView class properties. 
Let's look at an example. 

Example 

The following example is fetching the view's properties: 

Dim session As Object 
Dim db As Object 
Dim view As Object 

Set session = CreateObject("notes.notessession") 

Set db = session.getdatabase, "test.nsf") 

Set view = db.GetView("By Author") 

Print (view.Name) 

Following is an explanation of the code. 
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We declare a session, db and view which reference the NotesView object. 

Dim session As Object 
Dim db As Object 
Dim view As Object 

We get the reference to NotesView using the GetView method of 
NotesDatabase. 

Set view = db.GetView("By Author") 

We print out the Name of the view. 

Print (view.Name) 

Locating a View 

if the name of the view or folder is known, specify it to the GetView 
method of NotesDatabase. The view or folder name must be specified 
exactly, including cascades; for example, Gertificates and ID 
informationXGross Gertificates. if the name has a synonym, you can specify 
the name or the synonym. For example, if a view name is By Author and 
the synonym is AuthorView, you can specify it as 

"By Author" 

or 

"AuthorView" 

However, you cannot specify both the name and the alias using the OR 
operator. For example. By Author I AuthorView is not possible. 

if the name of the view or folder is not known, you can compare each view 
and folder in the Views property of NotesDatabase with one of the 
NotesView properties; for example, IsDefaultView or UniversallD. 

For more details, refer to the previous example. 

Deleting a View 

If you update a database by adding, deleting, or changing information, the 
updates are not reflected in a view or folder until they are refreshed. The 
user can refresh a view or folder by clicking the refresh button or choosing 
View - Refresh. 

If you want updates to automatically appear in a view or folder, call the 
Refresh method of NotesView after the update is complete. Document 
updates must first be posted to storage using the Save method of 
NotesDocument. 

If you want to remove a view or a folder, call the Remove method. 
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Let's look at an example. 

Example 

The following example shows how to rewrite the equivalent HiTest sample 
using Notes classes through OLE automation. This example also removes 
the $ALL view. 

Dim session As Object 

Dim db As Object 

Dim view As Object 

Set session = CreateObject("Notes.NotesSession") 

Set db = session.GetDatabase"test.nsf") 

Set view = db.GetView("$ALL") 

Call view.Remove 

Set view = Nothing 

Set db = Nothing 

Set session = Nothing 

Following is an explanation of fhe code. 

We declare view as an objecf which references NofesView. 

Dim view As Object 

We gef fhe reference fo NofesView using fhe GefView mefhod of 
NofesDafabase, and sfore if in view. 

Set view = db.GetView("$ALL") 

We delefe fhe $ALL view using fhe Remove mefhod of NofesView. 

Call view.Remove 

We release fhe NofesView objecf. 

Set view = Nothing 

Accessing Notes Folders 

Folders are a new feafure in Nofes Release. 4. A folder is a special kind of 
view. Folders lef you sfore and manage relafed documenfs wifhouf puffing 
fhem info a cafegory, which requires a Cafegories field in fhe form used fo 
creafe fhe documenfs. Folders are also convenienf because you can drag 
documenfs fo fhem. 
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The HiTest Visual Basic API does not support folders. If your applicafion 
needs fo access folders, you musf use Nofes classes fhrough OLE 
Aufomafion. 

Using Nofes classes fhrough OLE Aufomafion in Visual Basic, you can 
access Nofes folders fhe same way you access Nofes views. All fhe mefhods 
fhaf work wifh Nofes views also work wifh Nofes folders. 


Accessing Notes Views and Foiders in LotusScript 

Accessing Nofes views and folders using LofusScripf in Nofes works fhe 
same way as accessing views and folders in Visual Basic using Nofes classes 
fhrough OLE Aufomafion. However, you declare fhe variables referring fo 
fhe view or folder as a Nofes class rafher fhan as an objecf. 

In fhis parf of fhe chapfer, we will discuss fhe New mefhod of NofesView, 
which is new in Nofes Release 4.5. 

When you access Nofes views and folders in LofusScripf, you can use fhe 
Eorall and Eoreach sfafemenfs, which make your applicafion more simple. 
Lef's look af an example. 


Example 

This example accesses fhe view's properfies. You can puf fhis sample code 
on a new agenf in fhe TEST dafabase. Then choose fhe initialize function fo 
drive fhe scripf. 

Sub Initialized 

Dim session As New NotesSession 

Dim db As NotesDatabase 

Set db = session.CurrentDatabase 

REM view is a NotesView object 

REM cannot be Dim'd - loop reference variable 

Forall view In db.Views 

Messagebox "View name: " & view.Name & Chr(lO) _ 

& "Parent: " & view.Parent.Title & Chr(lO) _ 

& "Last modified: " & view.LastModified & Chr(lO) _ 
& "Created: " & view.Created & Chr(lO) _ 

& "Universal ID: " & view.UniversallD 
If view.IsDefaultView Then _ 
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Messagebox "Default view" 

If view.IsFolder Then Messagebox "Folder" 

End Forall 
End Sub 

Following is an explanation of the code: 

We process all the views in the db database. The view's properties, such as 
parent, LastModified, Created and UniversallD are processed using the 
syntax object.property. isFolder is a property of the view, which is defined 
as a folder. 

Forall view In db.Views 

Messagebox "View name: " & view.Name & Chr(lO) _ 

& "Parent: " & view.Parent.Title & Chr(lO) _ 

& "Last modified: " & view.LastModified & Chr(lO) 

& "Created: " & view.Created & Chr(lO) _ 

& "Universal ID: " & view.UniversallD 
If view.IsDefaultView Then _ 

Messagebox "Default view" 

If view.IsFolder Then Messagebox "Folder" 

End Forall 

Note in Lotus Notes Release 4.5, a new front-end class will be available, 
NotesUiView. This class can only be used in LotusScript, in an opened 
view, you can use this class to access the current view. 
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Chapter 9 

Accessing Notes Documents 


Documents are the primary components of databases. A Notes document is 
a database entry that contains information. A document may range in size 
from a brief reply fo a quesfion to a multi-page market analysis filled with 
text and graphics. Every document has certain IDs which provide varying 
levels of uniqueness. 

In this chapter, we will discuss how to access documents: 

• In HiTest 

• Using Notes classes through OLE automation in Visual Basic 

• Using LotusScript in Notes. 


Accessing Notes Documents Using the HiTest Basic API 

In HiTest, every document has certain IDs which provide varying levels of 
uniqueness. The mosf commonly used ID is fhe document ID which is 
unique within the document's database (t 5 q)e Long). Use this ID to 
reference individual documents. Sets of documents may be obtained from 
an index, which is produced by execufing a formula. 

The primary affribufes of a document are its HTDOCID, HTUNID, and 
HTOID values. To represent a document uniquely between databases, use 
either the universal ID (HTUNID) or the originator ID (HTOID). The 
universal ID is unique between databases but is the same for all replicas of 
the same document. The originator ID is unique among all other 
documents, including replicas (the universal ID is part of fhe originator ID). 

To access or manipulafe fhe contents of a document, the document must be 
opened. The HiTest API represents an open document by a document 
handle. A document handle is valid until closing either the document itself 
or the database containing the open document. The HiTest API uses the 
constant NULLHANDLE to represent an invalid document handle. 
Document decryption is handled automatically by the HiTest API when 
encrypted information is requested. 
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Accessing the Document Properties 

HTDocumentGetProperty function: Fetches one of various document-level 
property values into a supplied buffer. Each property has a data t 5 ^e, and 
the buffer must be large enough to hold the result. 

HTDocumentSetProperty fimction: Assigns a value to a document-level 
property. The type of the data is indicated by the property. 

Example 

This example sets the strict binding of all documents created after 
hgbegin_datetime to off. 

Dim hgdatabase As Long 

Dim hgdocid As Long 

Dim hgindex As Long 

Dim hgbegin_datetime As HTDATETIME 
Dim hgindent As Long 
Dim hgdocument As Long 
Dim hgstatus As Long 

hgstatus = HTInit(O) 

hgstatus = HTDatabaseOpen ("", "test.nsf", 0, hgdatabase) 

hgstatus = HTIndexOpen(hgdatabase, hgindex) 

hgstatus = HTIndexSearch(hgindex, "Select @A11", 0&, 
hgbegin_datetime) 

hgstatus = HTIndexNavigate(hgindex, HTNAV_END, 0&, hgdocid, 
hgindent) 

Do Until hgstatus = HTFAIL_END_OF_DATA 

hgstatus = HTDocumentOpen(hgdatabase, hgdocid, 0&, 
hgdocument) 

hgstatus = HTDocumentSetProperty(hgdocument, 
HTDOCUMENT_STRICT_BIND, False) 

hgstatus = HTDocumentClose(hgdocument, 0&) 

hgstatus = HTIndexNavigate(hgindex,HTNAV_NEXT, 0&, hgdocid, 
hgindent) 

loop 

hgstatus = HTDatabaseClose(hgdatabase, 0&) 
hgstatus = HTTerm(O) 
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Following is an explanation of the code. 

in HiTest, we present the index as long. We declare an hgindex variable 
which references the Notes index. 

Dim hgindex As Long 

We declare hgbegin_datetime as a Notes datetime item. 

Dim hgbegin_datetime As HTDATETIME 

We declare hgindent which references a buffer to receive the viewcell 
indentation of the new entry, in HiTest, we present it as long. 

Dim hgindent As Long 

This statement opens an index in the database specified by hgdatabase and 
returns the index value to the hgindex variable, if the open is unsuccessful, 
it will return an error code to hgstatus. 

hgstatus = HTIndexOpen(hgdatabase, hgindex) 

We produce hgindex, and have it contain only the documents created after 
hgbegin_datetime. if the function is unsuccessful, it will return an error 
code to hgstatus. 

hgstatus = HTIndexSearch(hgindex, "Select @A11", 0&, 
hgbegin_datetime) 

We navigate through the index specified by hgindex using a navigation 
style (direction and flags). HTNAV_END presents the navigation direction. 
The document id is returned to hgdocid and viewcell is returned to 
hgindent. 

hgstatus = HTIndexNavigate(hgindex, HTNAV_END, 0&, hgdocid, 
hgindent) 

We want to process all the documents in the index. Therefore, we will use a 
Do_Until-loop statement. 

Do Until hgstatus = HTFAIL_END_OF_DATA 
Loop 

We open the document specified by hgdocid in hgdatabase and return the 
handle of the document to hgdocument. if the open is unsuccessful, it will 
return an error code to hgstatus. 

hgstatus = HTDocumentOpen(hgdatabase, hgdocid, 0&, 
hgdocument) 

We set the strict binding of the document to off. The document is specified 
by hgdocment. in case of failure, an error code is returned to hgstatus. 
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hgstatus = HTDocumentSetProperty(hgdocument, 
HTDOCUMENT_STRICT_BIND, False) 

Then we close each document. If the document cannot be closed 
successfully, an error code is returned to hgstatus. 

hgstatus = HTDocumentClose(hgdocument, 0&) 

Creating a Document 

FTDocumentCreate function: Creates and opens a new document in the 
database. Once created, the document behaves like any other document. 

The new document will not have a valid document ID until written to disk 
with HTDocumentSave or HTDocumentClose. If the DELAY_COMMIT 
property is used when closing, a valid document ID will not be assigned 
until the containing database is closed. 

Example 

Creates a new empty document. 

Dim hgdatabase As Long 
Dim FormID As Long 
Dim hgdocument As Long 
Dim hgstatus As Long 

hgstatus = HTInit(O) 

hgstatus = HTDatabaseOpen("", "test.nsf", 0, hgdatabase) 

FormID = HTFormLocateByName(hgdatabase, "Main Topic") 
hgstatus = HTDocumentCreate(hgdatabase, FormID, hgdocument) 
hgstatus = HTDocumentClose(hgdocument, 0&) 

hgstatus = HTDatabaseClose(hgdatabase, HTDBCLOSEF_SAVE_DOCS) 
hgstatus = HTTerm(O) 

Following is an explanation of the code. 

We need to specify a form when we create a new document in the database. 
The form can be specified by the form ID. In HiTest, we present the form ID 
as long. 

Dim FormID As Long 

After opening a database, we specify the form ID by the form name. Here 
we use the Main Topic form of the TEST database. 

FormID = HTFormLocateByName(hgdatabase, "Main Topic") 
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We create and open a new document using FormID and hgdatabase. The 
document handle is returned to hgdocument. If this is unsuccessful, an 
error code is refurned to hgstatus referring to an invalid database or invalid 
form. 

hgstatus = HTDocumentCreate(hgdatabase, FormID, hgdocument) 

Removing a Document 

HTDocumentDelefe funcfion: Removes an entire document. 

It works this way: 

Declare Function HTDocumentDelete Lib "W3HTAPI.DLL" (ByVal 
hgdatabase As Long, ByVal hgdocid As Long, ByVal hgdocdelete_flags As 
Long) As Long 

'hgdatabase Input 

HTDocumentDelete ( hgdatabase, hgdocid, hgdocdelete_flags ) 


Functions 

Type 

Descriptions 

hgdatabase 

input 

The database containing the document 

hgdocid 

input 

The document id of the document to be deleted 

hgdocdelete_flags 

input 

Flags affect the operation of this function 


HTDOCDELETEF_NO_STUB: Do not save a 
deletion stub 

HTDOCDELETEE_DELAY_COMMIT: Override 
database delay commit property on 
HTDOCDELETEE_EORCE_COMMIT: Override 
database delay commit property off 


If fhe funcfion fails, an error code is refurned to hgstatus. Error codes 
include: 

HTFAIL_INVALID_DOCUMENT (document does not exist) 

HTEAIL_DESIGN_DOCLJMENT (non-data document without 
docopen_design) 

Copying a Document 

HTDocumentCopy function: Creates an entire hierarchy copy of fhe source 
document from a view-based index in the destination database. 

The function is defined as HTDocumentCopy(hgsrc_database, 
src-docid,desf_dafabase, desf_docid) 
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When the function is unsuccessful, if ref urns an error code fo hgsfafus. 
Failure codes include: 

HTFA1L_1NVAL1D_DATABASE (invalid desfinafion dafabase) 
HTFAlL_lNVALlD_DOCUMENT (source documenf does nof exisf) 

Other Functions to Work with Documents 

HTDocumenfClose: Closes an open documenf. 

HTDocumenfEncrypf: Encr 5 ^fs ifems wifhin a documenf. 

HTDocumenfExecufe: Execufes a formula againsf a documenf. 

HTDocumenfLocafeByClass: Locafes a unique documenf given ifs 
documenf class. 

HTDocumenfLocafeByUNlD: Locafes a unique documenf given ifs 
universal ID. 

HTDocumenfOpen: Opens a documenf for dafa access or modificafion. 
HTDocumenfSave: Saves changes fo an open documenf. 
HTDocumenfValidafe: Validafes an open documenf. 


Accessing Notes Documents in Visual Basic Using Notes Classes 
through OLE Automation 

We use fhe NofesDocumenf class fo access Nofes documenfs when we are 
using Nofes Classes fhrough OLE aufomafion in Visual Basic. The 
NofesDocumenf class lefs you examine and manipulafe documenf 
properfies and confenfs. You gain access fo a NofesDocumenf objecf 
fhrough mefhods provided by fhe NofesDafabase, NofesView, and 
NofesDocumenfCollecfion classes. 


Eollowing is a fable comparing equivalenf functions in HiTesf and in 
LofusScripf. 


HiTest Function Name 

Notes Classes 

Notes Methods and Properties 

Summary 

FITDocumentClose 



Closes an open 
document. 

FITDocumentCopy 

NotesDocument 

CopyToDatabase 

Copies a document 
between databases. 

FITDocumentCreate 

NotesDatabase 

CreateDocument 

Creates a new, 
empty document. 


Continued 
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HiTest Function Name 

Notes Classes 

Notes Methods and Properties 

Summary 

HTDocumentDelete 

NotesDocument 

Remove 

Deletes a document. 

HTDocumentEncrypt 

NotesDocument 

Encrypt 

Encrypts items 
within a document. 

HTDocumentExecute 



Executes a formula 
against a document. 

HTDocumentGetProperty 

NotesDocument 

Created, LastModified, 
LastAccessed, IsResponse, 
ParentDocumentUNID, 
NotelD, UniversallD, 
EncryptOnSend, 

SignOnSend, HasEmbedded, 
IsUnread (only for read only 
in Release. 4.5), 

ISUIDocOpen (only in 

Release. 4.5) 

Obtains a 
document-level 
property value. 

HTDocumentLocateByClass 



Locates a unique 
document given its 
document class. 

HTDocumentLocateByUnid 



Locates a document 
given its xmiversal 
ID. 

HTDocumentOpen 



Opens a document 
for data access or 
modification. 

HTDocumentSave 

N otesDocument 

Save 

Saves changes to an 
open document. 

HTDocumentSetProperty 

NotesDocument 

EncryptOnSend, 

SignOnSend, 

MakeResponse, Verifier, 
ETSearchScore, Parent View, 
IsNewNote, Responses, etc. 

Assigns the value of 
a document-level 
property. 

HTDocumentV alidate 



Validates an open 
document. 


NotesDocument 

MarkRead 

Marks document as 
read. 


NotesDocument 

MarkUnread 

Marks document as 
unread. 
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Accessing the Document Properties 

Notes classes provide different NotesDocument properties than provided 
by HiTest. Only EncryptOnSend, Encr 5 ^tionKeys, SaveMessageOnSend, 
and SignOnSend are read-write properties. The other properties are 
read-only properties. 

Eor more detailed information on NotesDocument, refer fo Chapfer 3. 
Lef's look af an example. 

Example 

This agenf example displays fhe properfies of fhe firsf documenf in fhe 
TEST dafabase. 

Dim session As Object 
Dim db As Object 
Dim dc As Object 
Dim doc As Object 

Set session = CreateObject ("Notes.NotesSession") 

Set db = session.GetDatabase ,"test.nsf") 

Set dc = db.AllDocuments 

Set doc = dc.GetFirstDocument(1247) 

Print ( "Created: " & doc.Created) 

Print ( "Last modified: " & doc.LastModified) 

Print ("Note ID: " & doc.NotelD) 

Eollowing is an explanation of fhe code. 

We declare dc as an objecf which will reference fhe documenf collecfion in 
fhe daf abase. 

Dim dc As Object 

We declare doc as an objecf which will reference fhe Nofes documenf. if 
descends from NofesDocumenfCollecfion. 

Dim doc As Object 

We gef a reference fo NofesDocumenf Collecfion from fhe AllDocumenf 
mefhod of NofesDafabase. 

Set dc = db.AllDocuments 

We gef a reference fo fhe firsf documenf using fhe GefEirsfDocumenf 
mefhod of fhe NofesDocumenf Collecfion objecf and sfore if in doc. 1247 
refers fo fhe dafabase type. 
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Set doc = dc.GetFirstDocument(1247) 

We get the date when the document was created using the Create Data 
property of NotesDocument. 

Print ( "Created: " & doc.Created) 

We get the document ID and last modified dafe using the NotesID and 
LastModified properties of NofesDocument and display them. 

Print ( "Last modified: " & doc.LastModified) 

Print ( "Note ID: " & doc.NotelD) 

Creating a Document 

We use the CreateDocument method of NofesDafabase fo create a Notes 
document. For an example, refer to Chapter 4. 

Removing a Document 

The Remove method of NofesDocument removes a document from a 
database. An argument permits you to force fhe removal (True) or make if 
dependent on the document not being modified by someone else since fhe 
program sfarted (False). 

Lef's look af an example. 

Example 

Dim session As Object 
Dim db As Object 
Dim dc As Object 
Dim doc As Object 

Set session = CreateObject("Notes.NotesSession") 

Set db = session.GetDatabase, "test.nsf") 

Set dc = db.AllDocuments 

Set doc = dc.GetFirstDocument(1247) 

Call doc.Remove(True) 

Following is an explanation of fhe code. 

We gef fhe firsf document in the document list. 1247 refers fo fhe database 
type. 

Set doc = dc.GetFirstDocument(1247) 

We remove the document using the Remove method of NofesDocument. 

Call doc.Remove(True) 
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Copying a Document 

Using Notes classes through OLE automation, the CopyToDatabase method 
copies a document to a specified database (which can be the same database 
in which the document exists). 

Let's look at an example. 

Example 

This example copies the first document in test.nsf to the testl.nsf database. 

Dim session As Object 
Dim db As Object 
Dim dbl As Object 
Dim dc As Object 
Dim doc As Object 

Set session = CreateObject("Notes.NotesSession") 

Set db = session.GetDatabase, "test.nsf") 

Set dc = db.AllDocuments 

Set doc = dc.GetFirstDocument(1247) 

Set dbl = session.GetDatabase ("","testl.nsf") 

Call doc.CopyToDatabase(dbl) 

Following is an explanation of fhe code: 

We gef fhe reference fo fesf.nsf. 

Set db = session.GetDatabase("", "test.nsf") 

We gef fhe reference fo fesfl.nsf. 

Set dbl = session.GetDatabase ("","testl.nsf") 

We copy fhe firsf document to testl.nsf. 

Call doc.CopyToDatabase(dbl) 

Accessing the Current Document 

We can access fhe document that is currently open through the 
NotesUlWorkspace and NotesUlDocument classes. The NotesUlWorkspace 
class has one property, CurrentDocument, which is a reference fo fhe 
current document, and has the following mefhods: 

NofesUlDocument = ComposeDocument(file, form) creafes a new 
document and makes it the current document. 
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NotesUIDocument = EditDocument([bool]) puts the current document in 
edit mode. 

For more information about the NotesCurrentDocument class, refer fo 
Chapfer 3. 

Lef's look af an example. 

Example 

This example execufes when fhe user enfers a field in edif mode. The scrip! 
displays informafion abouf fhe field and fhe documenf. You can fry fhis 
example on a form you creafed. 

Dim workspace As Object 

Dim uidoc As Object 

Set workspace = CreateObject("Notes.NotesUIWorkspace") 
Set uidoc = workspace.CurrentDocument 
If uidoc.EditMode Then 

If uidoc.IsNewDoc Then 
Print_ 

("This is the " & _ 
uidoc.CurrentField & " field") 

Else 

Print _ 

("This is the " & uidoc.CurrentField & _ 

" field of " & uidoc.WindowTitle) 

End If 
End If 
End Sub 

Folllowing is an explanafion of fhe code. 

Currenf documenf is a unique objecf class in Nofes. We declare uidoc as an 
objecf fo reference fhe currenf documenf. 

Dim uidoc As Object 

We gef a reference fo fhe currenf documenf using fhe Currenf Documenf 
properfy of fhe NofesUlSession class and store if in uidoc. 

Set uidoc = workspace.CurrentDocument 
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If the current document is in edit mode, we look at the document. If the 
document is a new document we display the current field. If not, we 
display the current field and specify the current document's window title. 

If uidoc.EditMode Then 

If uidoc.IsNewDoc Then 

Print _ 

("This is the " & _ 
uidoc.CurrentField & " field") 

Else 

Print _ 

("This is the " & uidoc.CurrentField & _ 

" field of " & uidoc.WindowTitle) 

End If 
End If 


Accessing Notes Documents in LotusScript 

When using LotusScript in Notes, you can use some methods that are not 
available in Visual Basic. This makes the code more simple and more 
powerful. 

Accessing the Document Properties 

The Authors property of NotesDocument is a string array which contains 
all the names of the authors. Using the Forall function provides you with 
easy access. 

Let's look at an example. 

Example 

This agent example displays the properties of the first document in the 
TEST database in a message box. The example is similar to the one in Visual 
Basic, however, using the Forall function, you will notice how easily you 
can get the author names. 

Sub Initialize 

Dim db As New NotesDatabase ("", "test.nsf")) 

Dim dc As NotesDocumentCollection 
Dim doc As NotesDocument 
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Set dc = db.AllDocuments 


Set doc = dc.GetFirstDocument() 

Forall docAuthor In doc.Authors 
Messagebox docAuthor 
End Forall 

Messagebox "Created: " & doc.Created 
Messagebox "Last modified: " & doc.LastModified 
Messagebox "Note ID: " & doc.NotelD 
End Sub 

Following is an explanation of the code. 

We declare dc as a Notes document collection object which descends from 
NotesDatabase. 

Dim dc As NotesDocumentCollection 

We declare doc as a Notes document object which descends from Notes 
Document Collection. 

Dim doc As NotesDocument 

We get a reference to NotesDocument Collection from the AllDocument 
method of NotesDatabase. 

Set dc = db.AllDocuments 

We get a reference to the first document using the GetFirstDocument 
method of the NotesDocument Collection object and store it in doc. 

Set doc = dc.GetFirstDocument0 

We get all the author names of the first document and put them in the 
message box. 

Forall docAuthor In doc.Authors 
Messagebox docAuthor 

End Forall 

We get the date when the document was created using the Create Data 
property of NotesDocument. 

Messagebox "Created: " & doc.Created 
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We get the document ID and last modified date using the NotesID and 
LastModified properties of NofesDocumenf and display fhem in message 
boxes. 

Messagebox "Last modified: " & doc.LastModified 
Messagebox "Note ID: " & doc.NotelD 

Creating a Document 

In LofusScripf we can use fhe New method of NofesDocumenf to create a 
new document in a database. 

Example 

This example creates a new document in a database and adds items to the 
Subject, Categories and Body fields of the new document. To run this 
example, use the TEST database created earlier. 

Sub Initialize 

Dim session As New NotesSession 

Dim db As NotesDatabase 

Dim view As NotesView 

Dim doc As NotesDocument 

Set db = session.CurrentDatabase 

Set doc = New NotesDocument(db) 

doc.Form = "Main Topic" 

doc.Subject = "LotusScript & HiTest VB API" 
doc.Categories = "Eastern" 
doc.Body = "OK" 

Call doc.Save(True, False) 

End Sub 

Following is an explanation of the code: 

We create a new document using the New method of NotesDocument. 

Set doc = New NotesDocument(db) 

We specify the form of the document using the Form property of the 
document. 

doc.Form = "Main Topic" 
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We enter text in the Subject, Categories and Body fields of fhe "Main Topic" 
documenf. 

doc.Subject = "LotusScript & HiTest VB API" 
doc.Categories = "Eastern" 
doc.Body = "OK" 

We save fhe new documenf. The documenf will be saved even if somebody 
fries fo access if while fhe scripf is running. 

Call doc.Save(True, False) 

Note Removing a documenf, copying a documenf, and accessing fhe 
currenf documenf works jusf fhe same as when using Nofes classes fhrough 
OLE automation in Visual Basic. Refer fo fhe appropriafe sections in fhis 
chapfer. 
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Chapter 10 

Accessing Notes Items 


In the user interface. Notes displays items in a document through fields on 
a form. When a field on a form and an ifem in a documenf have fhe same 
name, fhe field displays fhe ifem; for example, fhe Subjecf field displays fhe 
Subjecf ifem. 

In fhis chapfer, we will discuss how fo access Nofes ifems (fields): 

• In HiTesf 

• Using Nofes classes fhrough OLE aufomafion in Visual Basic 

• Using LofusScripf in Nofes. 


Accessing Notes Items (Fields) Using the HiTest Basic API 

There are five classes in HiTesf associafed wifh Nofes ifems: Ifem, Field, 
Affachmenf, CDRecord, and Composife. 


Items 

Nofes stores individual dafa values in ifems, which in furn make up 
documenfs. The HiTesf API sfrengfhens fhe somefimes vague disfincfion 
between fhe ferms ifem and field by always using ifem for documenf ifems 
and field for form fields. The primary affribufes of an ifem are an ifem 
name, a dafa type, and a data value. With the HiTest API, items can be 
accessed either from open documenfs, or by binding ifems fo fhe resulfs in 
an index. While Lofus Nofes ifself imposes no resfricfions on ifems wifhin a 
documenf, fhe HiTesf API adds a minimal sef of qualificafions which 
supporf basic access and facilifafe simpler ifem access. 

Fields 

A field is fhe componenf of a form which describes a single dafa ifem 
wifhin a documenf. Each form confains one or more fields. The primary 
affribufes of a field are a name and dafa type. When strict binding is in 
effect, all items within a document must have a corresponding field wifhin 
fhe documenf's form. 
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Attachments 

Internally, Lotus Notes stores file attachments as items of a particular data 
type. The HiTest API handles files differently since they may have different 
actions performed on them, specifically attaching and extracfing. Nofes 
sfores files attached to a document within items named $FILE, and these 
are the items accessed by the file functions. The primary affribufe of a file 
is a file name (which does nof include any pafh information). When 
affachments are creafed with the HiTest API, they are rendered through 
the Notes user interface af fhe end of their document. 

CDRecord 

CDRecord is a composite data record. One or more ordered CDRecords 
make up a composite data object. The primary attributes of a CDRecord are 
a CDRecord fype, an index within the composite, and usually a compound 
value (some CDRecords have no data beyond their type and index). The 
HiTest API does not support all CDRecord t 5 ^es available within Lotus 
Notes, although the common types are supported. Each CDRecord type 
which contains data is manipulated with a CDRecord structure prefixed 
with HTCD. 

Composites 

Composite data is synonymous with rich text or compound text. Composite 
objects are a special free-form compound data t 3 ^e within Lotus Notes. 
Each composite consists of one or more subcomponents called CDRecords. 
Internally, Notes stores a composite object as one or more items within a 
document. When using multiple items, the name is the same for all fhe 
ifems, and HiTesf handles and presents them as a single item. The primary 
attributes of a composife are an item name, a handle, and a value. HiTest 
uses the constant NULLHANDLE to represent an invalid composite 
handle. 

Let's have a look at some of fhe ifem funcfions: 

Copying an Item 

HTItemCopy Funcfion copies an item from one document to another. If an 
ifem of fhe same name exisfs in the destination document, that item is 
replaced. 

Example 

This example copies an item from one document to another and then 
deletes the item from the original document. In effect, it moves the item 
from one document to another. 

Dim hgstatus As Long 
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Dim hgdatabase As Long 
Dim hgindex As Long 

Dim hgbegin_datetime As HTDATETIME 

Dim hgdocid As Long 

Dim hgindent As Long 

Dim hgsrc_document As Long 

Dim hgdest_document As Long 

Dim hgitemname As String 

hgstatus = HTInit(O) 

hgstatus = HTDatabaseOpen("", "test.nsf", 0&, hgdatabase) 
hgstatus = HTIndexOpen(hgdatabase, hgindex) 

hgstatus = HTIndexSearch(hgindex, 0&, hgbegin_datetime) 

hgstatus = HTIndexNavigate(hgindex, HTNav_Next, 0&, hgdocid, 
hgindent) 

hgstatus = HTDocumentOpen(hgdatabase, hgdocid, 0&, 
hgsrc_document) 

hgstatus = HTIndexNavigate(hgindex, HTNav_Next, 0&, hgdocid, 
hgindent) 

hgstatus = HTDocumentOpen(hgdatabase, hgdocid, 0&, 
hgdest_document) 

hgitemname = "Subject" 

hgstatus = HTItemCopy(hgsrc_document, hgitemname, 
hgdest_document) 

If hgstatus = 0 Then 

Print hgitemname & " has been copied to the 
destination document." 

End If 

hgstatus = HTItemDelete(hgsrc_document, hgitemname) 

If hgstatus = 0 Then 

Print hgitemname & " has been deleted from the source 
document." 

End If 

hgstatus = HTDocumentClose(hgsrc_document, 0&) 
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hgstatus = HTDocumentClose(hgdest_document, 0&) 
hgstatus = HTIndexClose(hgindex) 
hgstatus = HTDatabaseClose(hgdatabase, 0&) 
hgstatus = HTTerm(O) 

Following is an explanation of the code. 

We declare hgsrc_document and hgdest_docment to reference the source 
and destination documents. 


Dim hgsrc_document As Long 
Dim hgdest_document As Long 

We declare hgitemname as the item name, in HiTest, a Notes item is 
specified by an item name and presented as long. 

Dim hgitemname As String 

After we get the reference of the source and destination document and store 
the handles in hgsrc_document and hgdest_document, we set the item 
name as "Subject". 

hgitemname = "Subject" 

We copy the field of the source document to the destination document. The 
field is specified by hgitemname. if copying is unsuccessful, an error code 
will return to hgstatus. 

hgstatus = HTItemCopy(hgsrc_document, hgitemname, 
hgdest_document) 

if the copying is successful, we print out a message to inform the user that 
the item has been copied. 

If hgstatus = 0 Then 

Print hgitemname & " has been copied to the 
destination document." 


We delete the item in the source document, if the action is unsuccessful, an 
error code will return to hgstatus. 

hgstatus = HTItemDelete(hgsrc_document, hgitemname) 

if the action is successful, we also print a message to inform the user. 

If hgstatus = 0 Then 

Print hgitemname & " has been deleted from the source 
document." 
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Deleting an Item 

The HTItemDelete function deletes an item from a document. This function 
does not work on file attachments (use the HTAttachment functions to 
manipulate or delete file attachments). Deleting a composite item deletes all 
items of that name from the document (the HiTest API considers all 
composite items of the same name as a single item). Deleting an open 
composite item (that is, represented by a valid composite handle) 
invalidates that composite handle. 

For more information, refer to the example on copying an item using 
HiTest. 


Accessing Notes Items (Fields) in Visuai Basic Using Notes Ciasses 
through OLE Automation 

When we use Notes classes through OLE automation in Visual Basic and 
LotusScript in Lotus Notes, there are three classes to work with Notes 
items: Notesltem, NotesEmbeddedObject and NotesRichTextltem. You gain 
access to these objects using various methods of the NotesDocument and 
NotesRichTextltem classes. 

The NotesRichTextltem class inherits from Notesltem, meaning that 
NotesRichTextltem objects can use all the properties and methods of 
Notesltem. 

NotesEmbeddedObject represents any one of the following: An embedded 
object, an object link and a file attachment. 

Note When we use the EmbedObject method of NotesRichTextltem in 
Visual Basic, the argument type of the method is type number rather than 
type constant which we can use in LotusScript. 


Type Constant 

Type Number 

EMBED_ATTACHMENT 

1454 

EMBED_OBJECT 

1453 

EMBED_OBJECTLINK 

1452 


Tip When using Notes classes through OLE automation, if Visual 
Basic cannot recognize a type, you can always use Message 
Cstr (TypeConstant) in LotusScript to find out the type number. 

Note The DoVerb method of NotesEmbeddedObject is used differently 
depending on the platform and the OLE server. Eor example, you use 
Embobj.DoVerb "&Open" in Windows 95, and Embobj.DoVerb "Edit" in 
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Windows 3.1. For details on the OLE server, refer to the appropriate OLE 
server documentation. 

Eollowing is a table which translates the HiTest functions to the equivalent 
Notes classes, methods and properties. 


HiTest Functions 

Notes Class 

Notes Class Properties 
and Methods 

Summary 

HTItemAppendText_List 

NotesDocument 

AppendToTextList 

Appends a text entry to 
a text list within a 
document. 

HTItemCopy 

NotesDocument 

Notesitem 

Copyltem 

CopyltemToDocument 

Copies an item from 
one document to 
another. 

HTItemDelete 

N otesDocument 

Removeltem 

Deletes an item from a 
document. 

HTItemDelete 

Notesitem 

Remove 

Deletes an item from a 
document. 

HTItemFetch 

NotesDocument 

GetItemValue, Hasitem, 
GetItemValue, Signer, 
IsSigned, Authors, 
GetNextItem in Release 4.5 

Converts and retrieves 
the data for an item into 
a supplied buffer. 


Notesitem 

Values, DateTimeValue 

Converts and retrieves 
the data for an item into 
a supplied buffer. 

HTItemGetCount 



Obtains the number of 
items in a document. 

HTItemGetInfo 



Obtains information 
about a document item. 

HTItemGetLength 



Obtains the length of an 
item as converted to a 
specified data type. 

HTItemList 

NotesDocument 

GetFirstItem, GetNextItem, 
Items 

Iterates through items in 
a document. 


Notesitem 

Name, ValueLength, Type, 
IsNames, IsReaders, 
IsAuthors, IsSigned, 
IsEncrypted, IsSummary, 
IsProtected 


HTItemPut 

N otesDocument 

Replaceltem, 
AppendItemValue, Sign, 
PutInFolder, 
RemoveFromFolder 

Writes an item to a 
document, overwriting 
any existing item of the 
same name. 


166 LotusScript for Visual Basic Programmers 



Copying an Item 

Use the CopyltemToDocument method of the Notesitem class to copy the 
current item to another document. Use the Copy Allitems method of 
NofesDocument to copy all items in the current document to another 
document. 

After copying an item, you must call the Save method for the 
NotesDocument object containing the new item. Otherwise the update is 
lost when the program exits. 

Let's look at an example: 

Example 

In the previous section on how to access Notes items in HiTest, we 
discussed an example showing how to copy a Subject item from the first 
document to the second document, and how to delete the original item. 
Following is the equivalent code using Notes classes through OLE 
automation in Visual Basic. 

Dim session As Object 

Dim db As Object 

Dim view As Object 

Dim doc_src As Object 

Dim doc_dest As Object 

Dim item As Object 

Set session = CreateObject ("notes.notessession") 

Set db = session.GetDatabase("", "test.nsf") 

Set view = db.GetView("By Author") 

Set doc_src = view.GetFirstDocument() 

Set doc_dest = view.GetNextDocument(doc_src) 

Set item = doc_src.GetFirstItem("Subject") 

Call item.CopyltemToDocument(doc_dest, "Subject") 

Call item.Remove 

Call doc_src.Save(True, False) 

Call doc_dest.Save(True, False) 

Set session = Nothing 
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Following is an explanation of the code: 

We declare doc_src and doc_dest which will reference the source (first) 
document and destination (second) document in the By Author View. 

Dim doc_src As Object 

Dim doc_dest As Object 

We declare item as an object which will reference the Subject item in the 
source document. 

Dim item As Object 

We get the reference to the source and destination documents using the 
view's methods: 

Set doc_src = view.GetFirstDocument() 

Set doc_dest = view.GetNextDocument(doc_src) 

We get the Subject item using the GetFirstitem method of NotesDocument. 

Set item = doc_src.GetFirstitem("Subject") 

We copy the Subject item of the source document to the destination 
document. 

Call item.CopyltemToDocument(doc_dest, "Subject") 

We remove the Subject item in the source document using the Remove 
method of Notesitem. 

Call item.Remove 

Deleting an Item 

Use either the Remove method of the Notesitem class or the Removeitem 
method of NotesDocument to remove an item from a document. The 
Remove method removes only the current object; other items with the same 
name remain in existence. The Removeitem method removes all items with 
the specified name. 

After removing an item, you must call the Save method for the 
NotesDocument object that contained the item or the update is lost when 
the program exits. 

For an example, refer to the section on how to copy an item using Notes 
classes through OLE automation. 
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Accessing Notes Items (Fields) in LotusScript 

By changing the declaration of the variables in Visual Basic using Notes 
classes through OLE automation, we can run the code as LotusScript code. 
Refer to the previous examples on how to copy or delete an item in Visual 
Basic using Notes classes through OLE automation. 

We can use the New method of Nofeslfem and NofesRichTextlfem in 
LofusScript. We can also use fhe Eorall and Eoreach sfafements fo enhance 
our code's performance. 

LofusScript also provides strong functions to access OLE objects. Let's look 
at an example. 

Example 

The following example shows how to access OLE objects using the 
EmbeddedObjects property of NofesDocument. The script accesses the last 
document in the All Documents view of HILL.NSE on a server called 
SanErancisco. 

The document contains the following: 

• A Word Pro embedded objecf called "Word Pro Document" in the 
Body item. 

• A Microsoft Excel object link called "MS® Excel Worksheet" in the 
Body item. 

• An Ami Pro embedded object, created in Notes Release 4, called "Ami 
Pro Document" in the Body item. 

• A file attachment called "CASTLE.BMP" in the Body item. 

• A Preelance Graphics embedded object called "Preelance Presentation" 
in the Description item. 

• A 1-2-3 embedded object called "123 Worksheet" that is embedded in 
the form used to create the document, and has been subsequently 
activated and edited by a user. 

This script uses the EmbeddedObjects property of NofesDocument, and 
displays the following: 

• "Word Pro Document" 

• "MS Excel Worksheet" 

• "Ereelance Presentation" 

• "123 Worksheet" 
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Dim db As NotesDatabase 


Dim view As NotesView 
Dim doc As NotesDocument 

Set db = New NotesDatabase( "SanFrancisco", "hill.nsf" ) 

Set view = db.GetView( "All Documents" ) 

Set doc = view.GetLastDocument 
Forall o In doc.EmbeddedObjects 
Messagebox( o.Name ) 

End Forall 

Following is an explanation of the code: 

We get a reference to the hilLnsf database on server SanFrancisco. 

Set db = New NotesDatabase! "SanFrancisco", "hill.nsf" ) 

We get the All Document view. 

Set view = db.GetView( "All Documents" ) 

We get a reference to the last document in the All Document view and store 
it in doc. 

Set doc = view.GetLastDocument 

We go through all the embedded objects in the last document and display 
their names. 

Forall o In doc.EmbeddedObjects 
Messagebox! o.Name ) 

End Forall 

For more information on LotusScript OLE objects, refer to Chapters 11 
and 12. 
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Chapter 11 

Using Notes as an OLE 2 Automation Client: Creating 
Objects 


This chapter describes how to create embedded and linked objects in a 
Notes document manually and using LotusScript. 

You can include data from other applications by adding embedded or 
linked objects to Notes documents. You can: 

• Embed part of a file in a Nofes documenf. 

• Embed an enfire file in a Nofes documenf. 

• Embed new dafa in a Nofes documenf. 

• Link a file fo a Nofes documenf. 


Creating an Embedded Object 

In fhis section you are going fo creafe an embedded objecf in a Nofes 
documenf. 

Embedding Part of a File in a Document 

You can embed dafa from anofher applicafion as an objecf in a Nofes 
documenf. This way, you can use an OLE server applicafion fo enfer and 
edif dafa in Nofes. This combines fhe feafures of Nofes fhaf facilifafe 
sharing fhe dafa wifh fhe cusfom feafures of applicafions fhaf can creafe 
dafa. Nofes becomes fhe "confainer" for fhe applicafion's dafa, and you can 
sfill use fhe original applicafion fo edif, modify, or add dafa. 

You can pasfe dafa from OLE server applicafions, and you can also drag 
and drop dafa from OLE 2 server applicafions. 

The following example shows how fo embed parf of a Lofus 1-2-3 file info a 
Nofes documenf. 

Creating a Notes Database and a Form 

Create a form for the OLE 2 database, and then use this form to embed or 
link a particular object in a Notes document. In our example, you will 
embed or link an object in a Notes rich text field. 
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Perform the following steps to create a form in Notes: 

1. Create a new database and save it with OLE 2 as the name. 

2. Create a form in the OLE 2 database and save it with OLE 2 Document 
as the name. 

3. Click the Design Eorm Properties Smarticon to display an infoBox and 
click on the arrow next to Versioning to display the list of available 
choices. 

4. Select Prior versions become responses. 

Tip You can also click the right mouse button and select Eorm 
Properties to display the infoBox. 

5. in the upper part of the Eorm Builder window, type OLE 2 in Lotus 
Notes Document and change the font size of the title line to 24 and the 
style to bold. 

Next, create an editable Ke 5 rwords field. 

6. On the next line, type Object Category:, which is static text. 

7. Click the Create Eield Smarticon to create the new field next to the 
static text and type ObjectCategory in the Name field. 

8. Under T 5 ^e, drop down the list of available choices and select 
Ke5rwords. 

9. in the list box under Choices, type two ke 5 rwords: Embedding and 
Linking. 

10. Click the interface tab, which is the second tab from the left on the 
infoBox, and select Radio button. 

11. Move the cursor to the next line, and under Object Category, type insert 
the object here:. 

12. Change the font size of the text to 12 and the style to bold. 

13. On the next line, create an editable rich text field and call it Object. This 
field will be used to store an embedded or a linked object. 

14. Move to the next line, tab a little to the right and type Date Created:. 

15. Create an editable Time field and call it Date. 

16. On the programming pane, select Eormula radio button and type 
©Created. 
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17. Press ESC and save the form. The form you jusf creafed should look 
like fhis: 


File Edit View Create Design Text Window Help 

B 1 1 i « i 3 Ifile ^paisl 

OLE 2 in Lotus Notes Document 


Object Category : | Ob|ectCategory I 


Insert the object here ; 

I Object ] 


Date Created 


: I Date || 


Pasting Data from an OLE Server Application into a Notes Document 

Now fhaf you have creafed a Nofes form, use fhis form fo creafe a Nofes 
documenf and pasfe dafa from a Lofus 1-2-3 documenf info fhe Nofes 
documenf. 

Note You musf leave Notes up and running. Minimize it, but do not close 
it. 

Perform the following steps to paste Lotus 1-2-3 data into a Notes 
document. 

1. First create a spreadsheet m Lotus 1-2-3. If you need help, refer to the 
Lotus 1-2-3 User's Guide. Here is an example of a spreadsheet: 



2. Select the data in the spreadsheet you want to embed and choose Edit - 
Copy to copy it to the clipboard. 

3. Switch to the Notes window and create a document based on the OLE 2 
Document form you created earlier. 

4. Click the Embedding radio button and click in the Object field. 

5. In the Notes document, choose Edit - Paste Special and select the 1-2-3 
Worksheet in the As: box. 
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Tip You can select Display as icon to display an icon rather than the 
embedded data. Notes displays the server application's icon by default. 
To display a different icon, click Change icon, select a different icon, 
and click OK. 

6. Click OK and save the document. The Notes document should look like 
this: 




Object Category : m Embedding 
C Linidwa 


Insert the object here : 


Quarterly Production Report 

1 Jerusry 

TR83439 

LK59930 

KD77743 

LP88378 

300000 

350000 

354000 

400000 

2 Fefimary 

TR83439 

LK5a930 

KD77743 

LP883T8 

410000 

410500 

408900 

412000 

3 March 

TR93439 

Ll<59930 

KD77743 

LP88378 

440000 

430000 

410000 

4400S00 



1 


Date Created : 30-05-96j 


Embedding an Entire Fiie in a Document 

You can embed an entire file created with another application as an object 
in a Notes document. This way, you can use an OLE server application to 
enter and edit data in Notes. 

The following example shows you how to embed a Lotus 1-2-3 file into a 
Notes document. 

1. Create a new Lotus 1-2-3 spreadsheet or use an existing spreadsheet 
and save it as OLE2TEST.WK4 in your Notes path, for example, 
c:\notes\data\123. Our spreadsheef looks like fhis: 


•tii' Fiie 

Edit 

yiaw Slyl® ZooIb Barge Window Help 






Sli 





B / u _ t . 

• a Jili 

I! 

A 

1 

nr- 

B 

l_c__ 

_0_ 

i 

F I 

[1 

IZZI 


2 

3 


Global Oil 

V?.. 1995 Budget 

4 




5 


In millions 

Q1 

Q2 

Q3 

Q4 

6 

INCOME 


7 

B 

Product Sales 

Services 

$25,000 

40000 

$25,000 
45800 ■ 

$25,000' 
32900 ■ 

$25,000 
43750 ■ 

9 

FACILITIES 


10 


Rent 

$2,200 

$2,200 

$2,200 

$2,200 

11 


Utilities 

200 

200 

300 

__250 

12 

COS 

iT OF GOODS SOLD 


13 

14 


Promotion 

Production 

$2,000 

400' 

$2,000 

475 

$12,000 

325' 

$2,000 

520' 

15 


Salary 

3000 

3000 

4000 

4000 

16 


Research and Development 

800' 

450' 

450 

600 

17 

OPERATING INCOME 

1 $66.4001 

$62.4751 

$38,6261 

$59,180 1 
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2. Switch to the Notes window and create a document based on the OLE 2 
Document form you created earlier on. 

3. Click the Embedding radio button and click in the Object field. 

4. Choose Creafe - Object and click the Create an object from a file radio 
buffon in fhe Creafe Objecf dialog box. 

5. In fhe Eile box, type c:\notes\data\123\ole2test.wk4. 

6. Click OK and save the document. The Notes document should look like 
this: 



OLE 2 in Lotus Notes Document 


Object Category 


S Embeddini 
0 Linkin^ 


Insert the object here : 


Global Oil 
1395 Budget 



Embedding a New Object in a Document 

You can embed a new object in a Notes document. This way, you can use 
an OLE server application to enter and edit data in Notes. 

When you create a new object. Notes opens a blank work file in fhe 
applicafion you selecf so you can enfer dafa. When you save fhe dafa, if is 
saved as an objecf in Nofes (insfead of as a separafe file). 

Note If you select an OLE 2 server application. Notes opens the blank 
work file direcfly in Nofes. 

In fhis example you embed dafa from Word Pro 96 info a Nofes documenf. 
Since Word Pro 96 is an OLE 2 server applicafion, you can edif a Word Pro 
96 file in a Nofes documenf direcfly (wifhouf larmching Word Pro 96) buf 
you musf have an insfailed copy of Word Pro 96. 

Note The user who receives this document from you will be able fo view if 
buf nof edit the Word Pro 96 document. 

To do so, follow fhese sfeps: 

1. Creafe a Nofes documenf based on the OLE 2 Document form you 
created earlier. 

2. Click the Embedding radio button and then click in the Object field. 
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3. Choose Create - Object from the menu bar. 

4. Select Lotus Word Pro 96 document, in the Object type box, then click 
OK. 

5. Type some phrases in Word Pro 96. When you edit the Word Pro 
document, in a Notes document, you are actually in a Word Pro 
environment. You can see the Word Pro icons at the bottom of fhe 
screen. They look like fhis : 

HbIv " 9 “‘^.■■‘'B'l'uliDBfauItTBXt 12:43PM 12-06-96 1 B Pg 1 


6. To leave the Word Pro environment editor, click an 5 nvhere in the Notes 
document outside the new object or press esc to leave the Word Pro 
environment editor. 

7. When you are done, save this Notes document. It should look like this: 


3 file Edit yiew Create lext Window help 


OLE 2 in Lotus Notes Document 

Object Category : || s i mhedding | 

I C Linking I 


Body \ y'T 

What is OLE? 

OLE (Object Linking and Embedding) is a technology that lets you share data 
between applications and is supported for Windows and Macintosh. OLE lets 
you embed or link data, such as a 1-2-3 chart, Word Pro document, or 
Freelance Graphics presentation, as an object in a Notes document. 

You can embed or link part of a file or an entire file from another application as 
an object in a Notes document. You can also embed a new object in a Notes 
document and use the object's application to enter data in Notes. For 
example, if you have 1-2-3, you could create a blank 1-2-3 worksheet object 
and enter 1-2-3 worksheet data in a Notes document 

Date Created : 31 -05-96 


Creating a Linked Object 

You can link data from another application as an object in a Notes 
document. This way, you can display the latest data from an OLE server 
application in Notes. A linked object is a pointer to data in another file; 
changes made to the original file are reflected in the Notes document. Notes 
asks whether to update (refresh) a linked object each time the document 
containing the object is opened. 

However, since the data is physically contained in a file on the file system 
of the PC in its server application format, you will "break" the link if you 
use Notes to e-mail the document or rely on this link in a Notes application. 
This is a major difference between linking an object and embedding it in the 
Notes object. 

The following example shows you how to link a Word Pro 96 file into a 
Notes document. 
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Linking Data to a Notes Document 

To link a Word Pro 96 document to a Notes document, follow these steps: 


1. Create a Word Pro 96 document and save it in \notes\data\wordpro, 
for example, in our example, we called fhe document OLE2TEST.LPW. 
It looks like this: 


U EilB Ed* View Cteeie lew Window Helo 


■Roedlh,sFi,a\ 



Read this first 

Note Ifyou were a Beta site or used the I'isitmaryCD programs to mstoH a Beta versioH of 
IVord Pro, you must clean ap yoar system before installing the released version Word Pro. 

See “Appendix A"fbr more bfomudiou. 

Tliis file contains the following updated and new information about Lotus® Word Pro*“ 96 
Edition: 

• Checking your package 

• Inslallii^ Word Pro 

• Notes and updates 

• Obtaining additional program files 

• New features in WordPro 

• Word Pro tips 

Checking your package 

Before you install Word Pro, lake lime now to check the disks and documentation in your Word 
Pro for Windows package. If your package is not complete, refer to “Missing or Defective 
Components’’ in the Lotus Customer Support Gutde\ 

2. Open fhe Word Pro documenf, selecf fhe dafa you wanf fo link and 
copy if fo the clipboard. 

3. Switch to the Notes window and create a document based on the OLE 2 
document form you created earlier on. 

4. Click the Linking radio button and then click in the Object field. 

5. Choose Edit - Paste Special from the menu bar. 

6. Click the Paste link to source radio button and select Word Pro 96 
document in the As: box. 


7. Click OK and save the document. The Notes document should look like 
this: 


□ file Edit 




OLE 2 in Lotus Notes Document 


Object Category 


C Embedding 
^_Unkin^^_ 


Insert the object here : 
Read this first 



Checking your package 



Chapter 11: Using Notes as an OLE 2 Automation Client: Creating Objects 177 





















Creating an Embedded Object Using LotusScript 

In this section you are going to create an embedded object in a Notes 
document using LotusScript. 

Using OLE automation in Notes allows you to combine the services Notes 
provides with the services of the OLE application. Notes can serve as the 
container for fhe applicafion, providing replication, securify, and access 
confrol as well as summarizing the data in views and making it possible to 
search for informafion using Nofes' full-fexf indexing capabilifies. The OLE 
applicafion can provide services fhaf would require exfensive efforf fo 
develop in Nofes, such as fhe cell engine from Excel or 1-2-3 or fhe 
sophisficafed fexf handling capabilifies of Word or Word Pro. 

Notes provides the very best container for these objects, as it frees users 
from having to learn the hierarchical file system (all Notes documents, even 
those with objects in them, can have a word-based title). In addition. Notes' 
development capabilities and integrated messaging services make using 
OLE applications as part of a workflow applicafion fasf and easy. 

Embedding an Entire Fiie in a Document 

You can embed an entire file from anofher applicafion as an objecf in a 
Notes document using LotusScript. 

The following example shows how fo embed data from a Lotus 1-2-3 
spreadsheet file info a Nofes documenf. 

1. Eirst, creafe a new Lofus 1-2-3 spreadsheef or use an exisfmg 

spreadsheef. In our example, we are using a new spreadsheef. It looks 
like this: 


Bis 

£dit yiew SVI® lools Beige J^^indow 

Help 


G11 





filfclala HilJimijal B' / lillEl 2( 

SIEE 

\ 1 o iBf^l 

A 

_ \t 

) B 

C 

D 

E 

1 

Directory of Current Versions 

2 


3 

Range Name 

Current Version 

i Creator 

Comments 

4 

PRODUCT.SALES 

Last Year's 

Jim 

What if W9 stick with the same 
three diskibutors as last yeah? 

5 

PROMOTION 

Last Year's 

Bob 

Assumes we use last year's 
advertising campaign and sales 
incentive programs 

6 

SALARY 

Last Year's 

Tony 

This would mean no increase in 
salary or headcount ~ it's v^at we 
spent last year 


2. Save this file as EMDBEILE.WK4 in your Nofes pafh, for example, 
d:\nofes\dafa\123. 
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3. Open the OLE 2 Notes database which you created earlier. The view 
window displays. 

4. On the navigator pane, select Design, then Forms and then double-click 
the OLE 2 Document form. The Form Design window displays. 

5. Move to the end of fhe form and choose Creafe - Hofspof - Buffon from 
fhe menu bar. 

6. Type Embed Objecf from a File in fhe Buffon label: box. 

7. Nexf fo Properfies for: Buffon, drop down fhe lisf of available choices 
and selecf Texf. Notice how fhe new buffon on fhe form now displays 
ifs fifle. 

Tip Wifh fhe buffon properfies still displayed, you can also highlighf 
fhe new buffon by dragging fhe cursor from leff fo righf. This 
aufomafically changes fhe buffon properfies fo fexf properfies. 

8. Click fhe fourfh fab from fhe leff and fhen selecf fhe Opened for reading 
check box. The Prinfed check box is selecfed aufomafically. 

9. On fhe programming pane, selecf fhe Scripf radio buffon. 

10. Click on fhe space befween Sub Click(Source As Buffon) and End Sub 
and type the following LofusScripf code: 

%INCLUDE "LSCONST.LSS" 

Sub Click (Source As Button) 

Dim workspace As New NotesUIWorkspace 

Dim uidoc As NotesUIDocument 

Dim fileName, msg As String 

Dim boxType As Long 

Set uidoc = workspace.CurrentDocument 

Call uidoc.FieldSetText ("ObjectCategory", 

"Embedding") 

Call uidoc.GotoField ("Object") 

Call uidoc.CreateObject ("1-2-3 Report", 

"D:\NOTES\DATA\12 3\EMBDFILE.WK4") 

Call uidoc.Save 

boxType = MB_OK + MB_ICONINFORMATION 
msg$ = (File has been embedded ! 

Click OK to close this document| 
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Messagebox msg$, boxType, "Successful" 

Call uidoc.Close 
End Sub 

11. Save the form and close it. 

Following is a description of the LotusScript code: 

Note in the following, when we explain our code samples, we will explain 
pieces of code only once, if the same piece of code reappears in a later 
sample, we will not explain it again. 

Declare workspace as an object reference variable of the NotesUiWorkspace 
class and create a new NotesUiWorkspace object. 

Dim workspace As New NotesUiWorkspace 

Declare uidoc as an object reference variable of the NotesUlDocument class. 

Dim uidoc As NotesUlDocument 

Declare fileName and msg as string variables and boxT 5 ^e as a Long 
variable. 

Dim fileName, msg As String 
Dim boxType As Long 

Assign uidoc as a reference variable of a current document object. 

Set uidoc = workspace.CurrentDocument 

Set the ObjectCategory item value with an Embedding string. 

Call uidoc.FieldSetText ("ObjectCategory", "Embedding") 

Move the cursor to the Object item. 

Call uidoc.GotoField ("Object") 

Create a new embedded object in the Object item. This embedded object is 
created from the EMBDFILE.WKT file located in the 
D:\NOTES\DATA\123 subdirectory. 

Note You will receive an error message if the file does not exist in the 
subdirectory or if it is being used by another process. 

Call uidoc.CreateObject ("1-2-3 Report", 

"D:\NOTES\DATA\12 3\EMBDFILE.WK4") 

Save the Notes document. 

Call uidoc.Save 
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Assign the button and icon constant name to the boxT 5 ^e variable. 

boxType = MB_OK + MB_ICONINFORMATION 
Assign the sbing to the msg variable. 
msg$ = I File has been embedded ! 

Click OK to close this document| 

Display a message, from the msg variable, in a message box labeled 
"Successful" and confaining a Yes and No buffon. 

Messagebox msg$, boxType, "Successful" 

Close fhe Nofes documenf. 

Call uidoc.Close 

Nexf, compose a documenf using fhis form. 

12. Choose Create - OLE 2 Document from the menu bar. 

13. Click the Embed Object from a Eile buffon. The spreadsheet is 
embedded in your document. It looks like this: 


□ 519 V* View Sreste 

OLE 2 in Lotus Notes Document 




Object Category 


9 Embodding 
C Uniting 



Insert the object here 


14. Save and close the document. 


Note You can also embed part of a file in a Nofes documenf using 
LofusScripf. To do so, you need fo use fhe object's native LotusScript 
function to access the object's data in the object's application. This can 
be a complex process. Therefore, if might be a better choice to manually 
embed part of a file in a Nofes documenf. 
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Embedding a New Object in a Document 

In this example we are using the OLE 2 Document form to embed an OLE 
object in a Notes document. Eirst, follow fhese sfeps fo modify fhe form by 
adding LofusScripf code: 

1. Open fhe OLE 2 Nofes dafabase. The view window displays. 

2. On fhe navigafor pane, selecf Design, fhen Eorms and open fhe OLE 2 
Documenf form. The Eorm Design window displays. 

3. Move fo fhe end of fhe form and click fhe cursor under fhe Embed 
Objecf from a Eile buffon. 

4. Choose Creafe - Hofspof - Buffon from fhe menu bar and type Embed 
New Data Object in the Button label: box. 

5. Next to Properties for: Buffon, drop down fhe lisf of available choices 
and selecf Texf. Notice how fhe new buffon on fhe form now displays 
ifs fifle. 

6. Click fhe fourfh fab from fhe leff and selecf fhe Opened for reading 
check box. The Prinfed check box is selecfed aufomafically. 

7. On fhe programming pane, selecf fhe Scripf radio buffon. 

8. Click on fhe space befween Sub Click(Source As Buffon) and End Sub 
and f 5 ^e fhe following LofusScripf code: 

Sub Click (Source As Button) 

Dim workspace As New NotesUIWorkspace 

Dim uidoc As NotesUIDocument 

Dim msg As String 

Set uidoc = workspace.CurrentDocument 

Call uidoc.FieldSetText ("ObjectCategory", _ 
"Embedding") 

Call uidoc.GotoField ("Object") 

Call uidoc.CreateObject ("Turbo 123", 

"123Worksheet") 

msg$ = I Switch to 1-2-3 Application to create 
spreadsheet now or 

click OK to leave this 1-2-3 object empty ! | 

Messagebox msg$, MB_OK + MB_ICONINFORMATION, _ 

"Information" 


182 LotusScript for Visual Basic Programmers 



Call uidoc.Close 


End Sub 

9. Save the form and close it. 

Following is a description of the LotusScript code: 

Create a new blank embedded object in the Object item. This embedded 
object is a Lotus 1-2-3 blank spreadsheet. The class name of this object is 
123 Worksheet. 


Call uidoc.CreateObject ("Turbo 123", "123Worksheet") 

Display a message, from the msg variable, in a message box labeled 
"Information" and containing an OK button. 

Messagebox msg$, MB_OK + MB_ICONINFORMATION, _ 

"Information" 


Next, compose a document using this form. 

10. Choose Create - OLE 2 Document from the menu bar. 

11. Click the Embed New Data Object button. You should see something 
like this: 


a<9^aiia,ai-di ■: bi /janiiaaiigiBiF.r ififi'fe iiiaita 


OLE 2 in Lotus Notes Document 


Object Category 


9 t rnbKilding 
BjLinkin^^^ 


Insert the object here ; 

I --3Workshee* 




Date Created : 

14-06-96 

lllnfarmelian -:n| 



L.. 



Note Clicking the Embed New Data Object button automatically 
launches Lotus 1-2-3 in the backgroimd. 

12. If you want to create the spreadsheet straight away, switch to Lotus 
1-2-3 and work with it. Do not click the OK button on the message 
window. 

13. When you are done, choose Eile - Close & Return to Lotus Notes from 
the 1-2-3 menu bar. 

14. Click Yes to confirm that you want to update the object. 
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Note If you do not want to create the spreadsheet straight away, click 
OK on the message window. A message prompts you whether or not to 
save the document. If you click Yes, the 1-2-3 object will be saved as a 
blank object. You can update it later on. 


Creating a Linked Object Using LotusScript 

In this section you will link data from another application as an object in a 
Notes document using LotusScript. The following example shows how to 
link an object from a Microsoft Word document into a Notes document. As 
we noted before, links are dependent on the directory structure of the file 
system because they do not store the object's data in the Notes data store. 
So, links can be broken if the document is mailed to a user who does not 
have the object's data in the same physical location on their machine. 

1. First, create a new MS Word document or use an existing one. If you 
need help to create this document, refer to the appropriate product 
manual. We called our document WDREADME.DOC. It looks like this: 



MICROSOFT WORD FOR WINDOWS 95 
Supplemental Information 

CONTENTS 

Setup Information 

Inst^ing an UPGRADE version of Word for Windows 95 
Setup on Windows NT 3 51 (or later) 

Using Help on Windows NT 3 51 Without Service Pack 1 
Removing Earlier Word Version's Help Files From Pa4i statement 
Using Disks with Distnbution Media Format (DMF) 

Printing EPS files in Windows 95 or Windows NT 

Equation Editor 

Lotus cc.Mail or Lotus Notes 

Field Codes: Bookmark and REF Fields 

Using Word 6.0 or Word 2.0 Templates with Word for Windows 95 
Word for Windows 95 Default Setiqi Options 
Using Foreign Language Proofing Tools with Word for Windows 95 
Using Microsoft Bookshelf \99A with Word for Windows 95 
WordBasic Errors with Word 6.0 Add-ins and Macros 
WordMail Information 

ODBC Not Included with Word for Windows 95 
Windows 95 for Pen Computing 

Updates to Getting Results with Microsoft Word for Windows 95 
-.) 

2. Open the OLE 2 Notes database. The view window displays. 

3. On the navigator pane, select Design, then Eorms and open the OLE 2 
Document form. The Eorm Design window displays. 

4. Move to the end of the form and click the cursor under the Embed New 
Data Object button. 

5. Choose Create - Hotspot - Button from the menu bar and type Link an 
Object from a Eile in the Button label: box. 
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6. Next to Properties for: Button, drop down the list of available choices 
and selecf Text. Notice how the new button on the form now displays 
ifs fifle. 

7. Click the fourth tab from the left and select the Opened for reading 
check box. The Printed check box is selected automatically. 

8. On the programming pane, select the Script radio button. 

9. Click on the space between Sub Click(Source As Button) and End Sub 
and type the following LofusScript code: 

Sub Click(Source As Button) 

Dim session As New NotesSession 

Dim db As NotesDatabase 

Dim doc As NotesDocument 

Dim rtitem As NotesRichTextItem 

Dim object As NotesEmbeddedObject 

Dim workspace As New NotesUIWorkspace 

Dim uidoc As NotesUIDocument 

Dim boxtype As Long 

Dim answer As Integer 

Set db = session.CurrentDatabase 

Set doc = New NotesDocument (db) 

Set rtitem = New NotesRichTextItem (doc, 

"Object") 

doc.Form = "OLE 2 Document" 
doc.ObjectCategory = "Linking" 
doc.Date = Date$ 

Set object = rtitem.EmbedObject _ 

(EMBED_OBJECTLINK, _ 

"D:\NOTES\DATA\MSWORD\WDREADME.DOC", _ 

"MS Word 6") 


boxtype = MB_YESNO + MB_ICONQUESTION 


Chapter 11: Using Notes as an OLE 2 Automation Client: Creating Objects 185 



answer% = Messagebox ("Object has beed linked" 

& Chr(lO) & "Save this document ?", _ 
boxtype, "Save ?") 

boxtype = MB_OK + MB_ICONINFORMATION 
If answer% = 6 Then 

Call doc.Save (True, False) 

Messagebox "Document has been saved", _ 
boxtype, "Saving Information" 

Else 

Messagebox "Document not saved", _ 
boxtype, "Saving Information" 

End If 

Set uidoc = workspace.CurrentDocument 
Call uidoc.Close 
End Sub 

10. Save the form and close it. 

Following is a description of the LotusScript code: 

Assign db as a reference variable to the current database object. 
Set db = session.CurrentDatabase 
Create a new document in the current database. 

Set doc = New NotesDocument (db) 

Create a new rich text item in the current document. 

Set rtitem = New NotesRichTextItem (doc, "Object") 

Set the Form item with a string of OLE 2 document, 

doc.Form = "OLE 2 Document" 

Set the ObjectCategory item with a string of Linking, 

doc.ObjectCategory = "Linking" 

Create a new linked object in the Object rich text item. This object 
linked from the WDREADME.DOC file located in the 
D:\NOTES\DATA\MSWORDsubdirectory. 
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Set object = rtitem.EmbedObject 


(EMBED_OBJECTLINK, _ 

"D:\NOTES\DATA\MSWORD\WDREADME.DOC", _ 

"MS Word 6") 

Display the message "Object has been linked. Save this document?" from 
the msg variable in a message box labeled "Save" containing a Yes and No 
button. This message box function returns a value when the button is 
clicked. 

answer% = Messagebox ("Object has beed linked" _ 

& Chr(lO) & "Save this document?", _ 
boxtype, "Save ?") 

Save this Notes document without creating a response document. 

Call doc.Save (True, False) 

Next, compose a document using this form. 

11. Choose Creafe - OLE 2 Documenf from fhe menu bar. 

12. Click fhe Link an Objecf from a File buffon. A message is displayed. 
Your Nofes documenf should look like fhis: 


File Edit yiew EreeJe ^iors Text ^ndow Help 

OLE 2 in Lotus Notes Document 


Object Category 


G Lmbedding 
O Linking 


Insert the object here : 


[ Embed Object from a File | 


lEmbed New Data Object 


[ Link an Object from a FilT^ 


Date Created : 18-06-96 




Object has beed linked 
Save this document ? 


|i .Yes "jI No 


Note You will receive an error message if fhe objecf file does nof exisf 
or if if is being used by anofher process. 

13. Click Yes fo save fhe documenf. 

14. Click OK fo close fhe documenf. 

Nexf, open fhe documenf. 

15. Display the Access OLE 2 view and open the document listed in the 
Linking category. 
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16. Click Yes to confirm that you want to refresh the link. The document 
should look like this: 


Q File Edit M9 w Crsal© Actions Documsnf Wmdo>v Hsip 

OLE 2 in Lotus Notes Document 


Object Category 


C Embedding 


Insert the object here : 


MICROSOFT WORD FORWINDOWS 95 
Supplemental Infcrmation 

CONTENTS 
Setup Information 

Instdlinj an UPGRADE version of Word for Windows 95 
Setup on Windows NT 3 5 1 (or later) 

Using Help on Windows NT 3 51 Without Servioe Pack I 
Removing Earlier Word Version's Help Files From Path staiement 
Usmg Dsks with Distnbuaon Media Format (DMF) 

Printing EPS files in Windows 95 or Wmdows NT 

Field Codes Bookmark and REF Fields 

Usmg Woid 6 0 or Word 2 D Templates with Word for Windows 95 
Word for Windows 95 Default Setup OpOons 

Usmg Microsoft Bookshelf 1 994 with Word for Windows 95 
WordBasic Errors wth Word 6 0 Add-ins and Macros 
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Chapter 12 

Using Notes as an OLE 2 Automation Client: Managing 
Objects 


This chapter describes how to edit and update an embedded or linked 

object in a Notes document manually and using LotusScript. 

You can do the following in a Notes document that contains an OLE object: 

• Edit an embedded object. You can edit an embedded OLE object's data 
by launching the object's server application from Nofes. You can edif an 
embedded OLE 2 objecf's dafa "in-place" by using fhe server 
applicafion's commands direcfly in Nofes. 

• Edif a linked objecf. You can edif a linked objecf's dafa by launching fhe 
objecf's server applicafion from Nofes. 


Editing an Embedded Object 

The following describes how fo edif an embedded objecf manually. 

Creating a View 

In our example here, before you edif Nofes documenfs fhaf confain 
embedded or linked objecfs, you firsf creafe a view in Nofes fo make if 
easier fo access each documenf. 

Eollow fhese sfeps fo creafe a view in Nofes: 

1. Open fhe OLE 2 dafabase. 

2. On fhe navigafor pane, click Design, fhen Views, and fhen double-click 
on fhe "^(unfifled) view. The View design window displays. 

3. Choose Design - View Properties from fhe menu bar and fype Access 
OLE 2 in fhe Name box. 

Tip You can also click fhe Design View Properfies Smarflcon. 

4. Click fhe Options fab and selecf fhe Show in View menu check box. 

5. Double-click on fhe "#" column fifle. 

6. Type Objecf Cafegory in fhe Tifle box; fhis is fhe fifle of your firsf 
column. 
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7. Select the Show twistie when row expandable check box. 

8. Click the Sorting Tab. 

9. Next to Sort, click the Ascending radio button, then, next to Type, click 
the Categorized radio button. 

10. Click the next tab on the InfoBox and select 12 in the Size box and Bold 
in the Style box. 

11. Click the Title tab and select 12 in the Size box and Bold in the Style 
box. 

12. On the programming pane, click the Field radio button and select the 
ObjectCategory field. Click Yes if fhe following message displayed: 



Nexf, creafe fhe second column. 

13. Double-click on fhe right of the Object Category column and type Date 
in the Title box, then select 5 in the Width box. 

14. Click the Sorting tab and, next to Sort, click the Ascending radio button. 

15. Click the next tab on the InfoBox, fhen selecf 10 in fhe Size box and Bold 
in fhe Style box. 

16. Click the Title tab, then select 12 in the Size box and Bold in the Style 
box. 

17. On the programming pane, select the Field radio button and click Yes if 
fhe message appears again, fhen selecf fhe Dafe field. 

18. Save this view, and on the navigator pane, select the Access OLE 2 
folder. The view should look like this: 


4 L- “1 J-- f 1 1 -> 



Object Category 

Date 


'' Embedding 


96/05/30 

96/05/31 

96/05/31 


'' Unking 

96/06/03 
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Editing the Object 

In this example you will edit the Notes document that contains the 
embedded object you created in the previous example. 


To edit the embedded OLE object in the Notes document, do the following: 


1 . 

2 . 

3. 


4. 

5. 


Open the Access OLE 2 view and highlight the first document listed in 
the Embedding category. 

Press Ctrl-E to put the document into edit mode. 

Double-click the Lotus 1-2-3 object and edit the spreadsheet data using 
Lotus 1-2-3. Eor example, insert a row to calculate the total figure for 
the production results of fhe quarfer. When you are done, fhe 
spreadsheef would look like fhis: 

'G22 ^ll^J 

/ il t * 3 J||4||:-i. X o HS ,ii||ft| 



In our example, nofice fhe Tofal row inserfed af fhe boffom of fhe 
spreadsheef. 

In Lofus 1-2-3, choose Eile - Updafe Lofus Nofes. 

Choose Eile - Exif & Refurn fo leave Lofus 1-2-3 and fo refum fo Lofus 
Nofes. Your Nofes documenf now looks like fhis: 


□ Elis Vd7 Visv. Create 

g.... .. . „ .1 


Object Category : I n Embedding I 
I C Linlang | 


Insert the object here : 

Quarterly Production Report 


January TR83439 

LK59930 
KD77743 
lP8a378 


-acrusry TR83438 

LK59930 
KD77743 
LP3837S 


LK5993Q 

KD77743 

LP88378 


300000 

350000 

351000 

4Cinnnn 


410000 

410500 

409300 

412000 


4400DD 

430000 

410000 

4400500 


6. Choose Eile - Save to save the document. 
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Note If you edit an embedded OLE 2 object in a Notes document, you can 
also edit the object directly without launching the object's application. 
However, you must have a copy of the object's application installed. For 
more details, see the section "Embedding a New Object in a Document" in 
the previous chapter. 


Editing a Linked Object 

You can edit a linked object's data by launching the object's server 
application from Notes. 

In the following example you will edit a Notes document that contains a 
linked Word Pro 96 object. To edit this linked object, do the following: 

1. Open the Access OLE 2 view and highlight the first document listed in 
the Linking category. 

2. Press Ctrl-E to put the document into edit mode. 

3. Click Yes when a message displays prompting you to refresh the object 
link between Notes and Word Pro 96: 



4. Double-click the Word Pro object. 

Note To edit a linked object, you need access to the linked file. If you 
removed or renamed the linked file, the following warning message is 
shown: 
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5. When Word Pro 96 is launched, edit the document. Our modified Word 
Pro document looks like this: 



|Read this first 

Note ^yoH were a Beta site or used dte Visionary CD programs to install a Beta *vrsion Word 
Pro, you must clean up your system bejore installing the released version of Word Pro. See “Appendix 
A "for more information. 


This file contains the following updated and new infoirnation about Lotus® Word Pro96 Edition 

• Checking your package 

• System requirements 

• Installing WordPro 

• Notes and updates 

• Obtaining additional program files 

• New features in Word Pro 

• WordPro tips 


Disks 

If your WordPro package is a retail package, it should contain one set of 3 5" high-density disks If your WordPro 
package is a Node Edition, it does not contain any disks If your computer requires a CD-ROM, Lotus will provide 
you with a CD-ROM version at no charge For information, refer to “Media Exchange” mthe Lotus Customer 
Support Guide 


Checking your package 

Before you install WordPro, take time now to check the disks and documentation m your Word Pro for Windows 
package If your package is not complete, refer to “Missing or Defective Components” m the Lotus Customer 
Support Gutck^ 

fimesNewRoman ~| 12'|giii~| B|iiu| qDefaultText '[ ']lO:31AM 96A)6A)7 ~ 

The data you change in the Word Pro 96 document is updated 
immediately in the Notes document unless the object's update type is 
Manual. 

6. Choose File - Save to save the changes. 

7. Choose File - Exit to return to Notes. The Notes document now looks 
like this: 




Read this first 

Mote if you were a Bela site or used die Visionaey CD programs to install a Beta version gf 
Word Pro, you nwst clean upyour syaarm h^ore insralliug the released vession if Word Pro. 
See “Appendix A'*for more bformadon. 

le contains the following updated and new informaticn about Lotus® Word Pro’'" 96 Edition 


Object Category : c tmbedding 
Iftsert the object here : 


Disks 

:f your Word Pro package is a retail package, it 
• Pro package is a Node EdiUon, it does nc 
mil provide yc«j with a CD-ROM versior 

Checking your package 


le set of 3 5" high-density di 


Note If the object's update type is Manual, press F9 to refresh the 
modified Word Pro 96 data in the Notes document. 

8. Save the document. 
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Editing an Embedded or a Linked Object Using LotusScript 

You can edit an embedded or a linked object in a Notes document using 
LotusScript. The following example shows you how to do this. 

1. Open the OLE 2 Notes database. The view window displays. 

2. On the navigator pane, select Design, then Forms and open the OLE 2 
Document form. The Form Design window displays. 

3. Move fo fhe end of fhe form and click fhe cursor under fhe Edif 
Embedded or Linked Objecf buffon. 

4. Choose Creafe - Hofspof - Buffon from fhe menu bar. An InfoBox 
displays. If lefs you sef fhe properfies of fhe new buffon. 

5. Type Edif Embedded or Linked Objecf in fhe Buffon label: box. 

6. Nexf fo Properfies for: Buffon, drop down fhe lisf of available choices 
and selecf Texf. Notice how fhe new buffon on fhe form now displays 
ifs fifle. 

Tip Wifh fhe buffon properfies still displayed, you can also highlighf 
fhe new buffon by dragging fhe cursor from leff fo righf. This 
aufomafically changes fhe buffon properfies fo fexf properfies. 

7. Click fhe fourfh fab from fhe leff and selecf fhe Opened for reading 
check box. The Prinfed check box is selecfed aufomafically. 

8. On fhe programming pane, selecf fhe Scripf radio buffon. 

9. Click on fhe space befween Sub Click(Source As Buffon) and End Sub 
and type the following LofusScripf code: 

Sub Click(Source As Button) 

Dim session As New NotesSession 

Dim db As NotesDatabase 

Set db = session.CurrentDatabase 

Dim collection As NotesDocumentCollection 
Set collection = db.AllDocuments 

Dim doc As NotesDocument 

Dim object As NotesEmbeddedObject 

Dim rtitem, handle As Variant 

Set doc = collection.GetNthDocument (7) 
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Set rtitem = doc.GetFirstItem ("Object") 


If rtitem.Type = RICHTEXT Then 

Forall o In rtitem.EmbeddedObjects 

Set object = rtitem.GetEmbeddedObject 
(o.Name) 

Set handle = object.Activate (True) 

End Forall 
End If 
End Sub 

10. Save this form and close it. 

Following is a description of the LotusScript code: 

Declare collection as an object reference variable of the 
NotesDocumentCollection class. 

Dim collection As NotesDocumentCollection 

Assign collection as a reference variable to all documents in the current 
database. 

Set collection = db.AllDocuments 

Declare object as an object reference variable of class 
NotesEmbeddedObject. 

Dim object As NotesEmbeddedObject 

Assign doc as a reference variable to the seventh document in the collection 
of documents. 

Set doc = collection.GetNthDocument (7) 

Assign rtitem as a reference variable to the object item in the current 
document. 

Set rtitem = doc.GetFirstItem ("Object") 

The following statement tests the rtitem variable to see if it is rich text or 
not. 

If rtitem.Type = RICHTEXT 

This statement assigns object as a reference variable to an object name in the 
object rich text item. 

Set object = rtitem.GetEmbeddedObject (o.Name) 
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The object's application is launched according to the object type in the 
object rich text item. 

Set handle = object.Activate (True) 

Next, compose a document using this form. 

11. Choose Create - OLE 2 Document from fhe menu bar. 

12. Click fhe Edif Embedded or Linked Objecf buffon. 

When you use fhis LofusScripf code fo edif an embedded objecf, OLE 2 
launches fhe objecf's applicafion and displays fhe objecf's dafa in fhis 
applicafion for a while. To display fhe dafa permanenfly and fo manipulafe 
fhe objecf dafa in ifs nafive applicafion, you need fo modify fhe above 
LofusScripf code by adding some nafive LofusScripf funcfion for fhe objecf. 

Eor example, if you edif a Word Pro documenf, you can add some Word 
Pro nafive funcfion in your LofusScripf code fo edif or manipulafe fhe 
Word Pro objecf's dafa. Eor more informafion on fhe functions fhaf can be 
accessed by OLE 2 and Nofes, refer fo fhe producf manuals provided wifh 
fhe objecf's applicafion. 


Deleting an Embedded or a Linked Object Using LotusScript 

You can delefe an embedded or a linked objecf in a Nofes documenf using 
LofusScripf. in fhe following example you will delefe an embedded or 
linked objecf based on fhe objecf name fhaf you enfer. 

Eollow fhese sfeps fo creafe LofusScripf code for delefing an embedded or a 
linked objecf in a Nofes documenf: 

1. Open fhe OLE 2 Nofes dafabase. The view window displays. 

2. On fhe navigafor pane, selecf Design, fhen Eorms, and open fhe OLE 2 
Documenf form. The Eorm Design window displays. 

3. Move fo fhe end of fhe form and click fhe cursor under fhe Edif 
Embedded or Linked Objecf buffon. 

4. Choose Creafe - Hofspof - Buffon from fhe menu bar and fhen type 
Delete Object in the Button label: box. 

5. Next to Properties for: Buffon, drop down fhe lisf of available choices 
and selecf Texf. Notice how fhe new buffon on fhe form now displays 
ifs fifle. 

Tip Wifh fhe buffon properfies still displayed, you can also highlighf 
fhe new buffon by dragging fhe cursor from leff fo righf. This 
aufomafically changes fhe buffon properfies fo fexf properfies. 
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6. Click the fourth tab from fhe leff, which allows you fo specify securify 
seffings. 

7. Selecf fhe Opened for reading check box. The Prinfed check box is 
selecfed aufomafically. 

8. On fhe programming pane, selecf fhe Scripf radio buffon. 

9. Click on fhe space befween Sub Click(Source As Buffon) and End Sub 
and type the following LofusScripf code: 

Sub Click(Source As Button) 

Dim session As New NotesSession 

Dim db As NotesDatabase 

Set db = session.CurrentDatabase 

Dim view As NotesView 

Dim docl, doc2 As NotesDocument 

Set view = db.GetView ("Access OLE 2") 

Set docl = view.GetDocumentByKey ("Embedding") 

Set doc2 = view.GetNextDocument (docl) 

Dim object As NotesEmbeddedObject 
Dim rtitem As Variant 

Set rtitem = doc2.GetFirstItem ("Object") 

If rtitem.Type = RICHTEXT Then 

Forall o In rtitem.EmbeddedObjects 

Set object = rtitem.GetEmbeddedObject 
(o.Name) 

Call object.Remove 

Call doc2.Save (True, True) 

End Forall 
End If 
End Sub 

10. Save fhis form and close if. 
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Following is a description of the LotusScript code: 

Declare view as an object reference variable of the NotesView class. 

Dim view As NotesView 

Assign view as a reference variable to the Access OLE 2 view. 

Set view = db.GetView ("Access OLE 2") 

Assign docl as a reference variable to the column value (Embedding) 
within the current view (Access OLE 2). 

Set docl = view.GetDocumentByKey ("Embedding") 

Assign doc2 as a reference variable to the document following docl in the 
current view. 

Set doc2 = view.GetNextDocument (docl) 

Assign rtitem as a reference variable to the object item in the current 
document. 

Set rtitem = doc2.GetFirstItem ("Object") 

This method removes the object in the current rich text item. 

Call object.Remove 

Save this changed document without creating the response document. 

Call doc2.Save (True, True) 

Next, compose a document using this form. 

11. Choose Create - OLE 2 Document from the menu bar. 

12. Click the Delete Object button. The embedded object is removed from 
the document. 

More Examples 

in this example you will activate a linked object in a Notes document based 
on the object's name. The user enters the object name and the LotusScript 
code will search the object in all Notes documents in the current database. 
When the object is found, LotusScript will examine the object type, if the 
object is a linked object, LotusScript will display a prompt for activating the 
object's application, if the object is an embedded object, LotusScript will 
display a message indicating that this object cannot be activated using this 
LotusScript code. 
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Add a button to the OLE 2 Document form and t 5 ^e the following 
LofusScripf code for fhis buffon: 

Sub Click (Source As Button) 


Dim session As New NotesSession 

Dim db As NotesDatabase 

Set db = session.CurrentDatabase 

Dim collection As NotesDocumentCollection 
Set collection = db.AllDocuments 

Dim object As NotesEmbeddedObject 

Dim doc As NotesDocument 

Dim rtitem, handle As Variant 

Dim objName, className, _ 

msg, msgl, msg2, msgS As String 

Dim found, answer As Integer 

Dim boxType As Long 

objName = "" 

objName = Ucase (Trim (Inputbox ( _ 

"Enter the object name : ", "Object Name", , 

If Trim (objName) <> "" Then 

Set doc = collection.GetFirstDocument 
found = False 

Do 

Set rtitem = doc.GetFirstItem ("Object") 
If rtitem.Type = RICHTEXT Then 

Set object = rtitem.GetEmbeddedObject 

If Not (object Is Nothing) Then 


30, 25))) 


(objName) 
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Select Case object.Type 


Case EMBED_OBJECTLINK 

className = object.Class 

msgl = "This is a LINKED object " & Chr (10) 
msg2 = "The object class name is " & _ 
className & Chr (10) 

msgS = "Click OK to activate this object" 
boxType = MB_OKCANCEL + _ 

MB_ICONINFORMATION 


answer = Messagebox (msgl & msg2 & msg3, _ 
boxType, "Object Information") 

If answer = 1 Then 

handle = object.Activate (True) 

Else 

Exit Sub 
End If 
found = True 

Case EMBED_OBJECT 

className = object.Class 

msgl = "This is an EMBEDDED object " & Chr 

( 10 ) 

msg2 = "The object class name is " & _ 
className & Chr (10) 

msg3 = "You cannot edit this object" & _ 

" using this LotusScript code" 
boxType = MB_0K + MB_ICONINFORMATION 

Messagebox msgl & msg2 & msg3, _ 
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boxType, "Object Information 
found = True 


End Select 

End If ' not object is nothing 
End If ' rtitem = RICHTEXT 
Set doc = collection.GetNextDocument (doc) 

Loop Until doc Is Nothing ' Or found 

If Not found Then 

boxType = MB_OK + MB_ICONSTOP 

msg = "Object " & objName & " not found !" 

Messagebox msg, boxType, "Object not found" 

End If 
Else 

Exit Sub 

End If ' objName is not Null 
End Sub 

Following is a description of the LotusScript code: 

Enter the object's name using the input box function. This function will 
display "Enter the object name: " in the inputbox window labeled Object 
name in the screen's coordinate 30, 25. The object name is converted into 
uppercase characters after removing the leading and trailing spaces. 

objName = Ucase (Trim (Inputbox ( _ 

"Enter the object name : ", "Object Name", , 30, 25))) 

Verify if the objName variable is empty by removing the leading and 
trailing spaces. 

If Trim (objName) <> "" Then 

Assign the doc as a reference variable fo fhe firsf document in the collection 
of documents. 

Set doc = collection.GetFirstDocument 

Assign the rtitem as a reference variable fo fhe Objecf ifem in the first 
document. 

Set rtitem = doc.GetFirstItem ("Object") 
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This statement assigns object as a reference variable to the object name in 
the object rich text item. 

Set object = rtitem.GetEmbeddedObject (objName) 

Verify if the object name in the current document is equal to the object 
name entered by the user. 

If Not object Is Nothing Then 

Verify if the object type is a linked object. 

Case EMBED_OBJECTLINK 

Set the className variable with the object's class name. 

className = object.Class 

Set the boxTjqje variable with OKCANCEL button and icon information 
values. 

boxType = MB_OKCANCEL + _ 

MB_ICONINFORMATION 

Display the messages from the in msgl, msg2, msg3 variables in a message 
box labeled "Object Information" containing an OK and a Cancel button. 
This message box function returns a value when the button is clicked. 

answer = Messagebox (msgl & msg2 & msg3, _ 

boxType, "Object Information") 

Verify if the clicked button is the OK button. 

If answer = 1 Then 

Load the object, through OLE, in the Notes document by displaying the 
user interface of fhe server applicafion. 

handle = object.Activate (True) 

Assign the doc as a reference variable fo fhe next document in the collection 
of documents. 

Set doc = collection.GetNextDocument (doc) 

Verify the value of doc and the found variables. If one of fhe variable values 
is frue, fhe loop is terminafed. 

Until (doc Is Nothing ) Or found 

Exit from this click procedure. 

Exit Sub 
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Appendix A 

HiTest and LotusScript Notes Classes: Comparing 
Functions 

The following table lists equivalent functions in HiTest and LotusScript. 
Not all the properties and methods of LotusScript Notes classes are listed 
here. For more detailed information on LotusScript Notes classes, refer to 
Chapter 3. 

The LotusScript Notes classes, properties and methods shown in italics will 
be available in Lotus Notes Release 4.5. 

Note that not all the LotusScript Notes classes, methods and properties can 
be used in Visual Basic through OLE automation. 

HiTest HiTest Functions LotusScript Notes Classes LotusScript Notes Classes: 

Class Properties and Methods 

ACL 


HTACLAdd 

N otes ACLEntry 

Name, CanCreateDocuments, 
CanDeleteDocuments, 
CanCreatePersonalAgent, 
CanCreatePersonalEolder 

HTACLDelete 

NotesACLEntry 

Remove 

HTACLGetRole 

NotesACLEntry 

Roles, IsRoleEnabled 

HTACLGetRoleName 

NotesACLEntry 

Roles 

HTACLList 

NotesACLEntry 

GetFirstEntry, GetNextEntry 

HTACLLookup 

N otes ACLEntry 

GetEntry 

HTACLReset 



HTACLSetRole 

NotesACLEntry 

AddRole, DeleteRole, EnableRole, 
DisableRole 

HTACLSetRoleName 

NotesACLEntry 

RenameRole 

HTACLUpdate 

N otes ACLEntry 

Save 


Continued 
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HiTest 

Class 

HiTest Functions 

LotusScript Notes Classes 

LotusScript Notes Classes: 

Properties and Methods 

Agent 

HTAgentCopy 

HTAgentCreate 

HTAgentDelete 

Notes Agent 

Remove 


HTAgentExecute 

NotesAgent 

Run 


HTAgentFetch 

Notes Agent 

Name, Owner, ServerName, Query, 
Comment 


HTAgentList 

NotesAgent 

Name, IsPublic 


HTAgentLocateByName 

NotesDatabase 

GetAgent 

Attachment 

HTAttachmentAttach 




HTAttachmentDelete 




HTAttachmentExtract 

N otesDocument 

GetAttachment 


HTAttachmentList 

RichTextItem 

FindEmbeddedObject 

CDRecord 

HTCDRecordDelete 




HTCDRecordFetchXxxx 

RichTextItem 

GetFormattedT ext 


FlTCDRecordGetCount 




FlTCDRecordGetlnfo 




FlTCDRecordlnsertXxxx 

RichTextItem 

AppendText, AddTab, AddNewline, 
AppendDocLink, EmbedObject, 
AppendRTItem 


FlTCDRecordList 

RichTextItem 

EindEmbeddedObject 


FlTCDRecordMakeDoclink 

RichTextItem 

AppendDocLink 


FlTCDRecordUpdateXxxx 



Column 

FlTColumnFetch 

NotesViewColumn 

Title, ItemName, Eormula, Position, 
IsSorted, IsCategory, IsFIidden, 
IsResponse 


FlTColumnGetCount 

NotesViewColumn 



FlTColumnList 

NotesViewColumn 

Title, ItemName, Formula, Position, 
IsSorted, IsCategory, IsFIidden, 
IsResponse 


Continued 
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HiTest 

Class 

HiTest Functions 

LotusScript Notes Classes 

LotusScript Notes Classes: 

Properties and Methods 

Composite 

HTCompositeClose 




HTCompositeConvertDocument NotesDocument 

RenderT oRTItem 


HTCompositeCopy 

HTCompositeCopySubset 

HTCompositeCreate 

NotesDocument 

New, AppendRTFFile 



NotesDocument 

CreateRichT extitem 


HTCompositeExport 

HTCompositeGetFont 

HTCompositeGetProperty 

HTCompositeImport 

HTCompositeListExport 

HTCompositeListImport 

HTCompositeListText 

HTCompositeMerge 

HTCompositeOpen 

HTCompositePutFont 



Database 

HTDatabaseClose 

NotesDatabase 

Close 


HTDatabaseCompact 

NotesDatabase 

Compact 


HTDatabaseCopy 

NotesDatabase 

CreateCopy, CreateReplica 


HTDatabaseCreate 

NotesDatabase 

New, Create, CreateFromTemplate 


HTDatabaseCreateFTIndex 

NotesDatabase 

UpdateFTIndex 


HTDatabaseDelete 

NotesDatabase 

Remove 


HTDatabaseDeleteFTIndex 




HTDatabaseGetProperty 

NotesDatabase 

IsFTIndexed, Created, LastFTIndexed, 
TemplateName, DesignTemplateName, 
FileName, FilePath, LastModified, 
ReplicalD, Server, Size, PercentUsed, 
Title, Categories 


HTDatabaseList 

DbDirectory 

GetFirstDatabase, GetNextDatabase 


HTDatabaseListCatalog 

HTDatabaseLocateByReplicaid 

NotesDatabase 

OpenByReplicalD 


Continued 
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HiTest 

Class 

HiTest Functions 

LotusScript Notes Classes 

LotusScript Notes Classes: 

Properties and Methods 


HTDatabaseLocateByTitle 

HTDatabaseOpen 

NotesDatabase 

Open 


HTDatabaseSetProperty 

NotesDatabase 

Title, Categories, IsOpen, Managers, 
Views, Agents, Parent, 
IsPublicAddressBook, 
IsPrivateAddressBook, ACL, 
CurrentAccessLevel, AllDocuments, 

Size, UnprocessedDocuments 

Datetime 

HTDatetimeAdjust 

NotesDateTime 

Adjust Second, AdjustMinute, Adjust 
Hour, AdjustDay, Adjust Month, Adjust 
Year 


HTDatetimeCompare 

NotesDateTime 

TimeDifference 


HTDatetimeConstant 

NotesDateTime 

SetAnyTime, Set Any Date 


HTDatetimeCreate 

NotesDateTime 

New 


HTDatetimeFetch 

NotesDateTime 

TimeZone, IsDT 


HTDatetimeGetCurrent 

N otesDateT ime 

SetNow 


HTDatetimeGetDiff 

NotesDateTime 

T imeDifference 


HTDatetimeGetProperty 



Document 

HTDocumentClose 




HTDocumentCopy 

N otesDocument 

CopyToDatabase 


HTDocumentCreate 

NotesDocument 

New 


HTDocumentDelete 

N otesDocument 

Remove 


HTDocumentEncrypt 

NotesDocument 

Encrypt 


HTDocumentExecute 




HTDocumentGetProperty 

N otesDocument 

Created, LastModified, LastAccessed, 
IsResponse,ParentDocumentUNID, 
NotelD, UniversallD, EncryptOnSend, 
SignOnSend, HasEmbedded 


HTDocumentLocateByClass 

HTDocumentLocateByUnid 

HTDocumentOpen 

HTDocumentSave 

NotesDocument 

Save 


Continued 
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HiTest 

HiTest Functions 

LotusScript Notes Classes 

LotusScript Notes Classes: 

Class 



Properties and Methods 


HTDocumentSetProperty 

N otesDocument 

EncryptOnSend, SignOnSend, 
MakeResponse 


HTDocumentV alidate 



Error 

HTErrorFetch 




HTErrorGetInfo 



Field 

HTFieldFetch 




HTFieldGetCount 




HTFieldList 



Fonts tyle 

Description 



Form 

HTFormCopy 




HTFormCreate 




HTFormDelete 

NotesForm 

Remove 


HTFormFetch 

NotesForm 

Aliases, Field, Formllsers, IsSuhform, 
Name, ProtectReaders, Readers, 

ProtectUsers 


HTFormList 




HTFormLocateByName 

NotesDatabase 

GetForm 

Format 

Description 



Index 

HTIndexClose 

HTIndexCopyHierarchy 

HTIndexDeleteHierarchy 

HTIndexFTSearch 

NotesView 

FTSearch, Clear 


HTIndexGetCount 

N otesDocumentCollection 

Count 


HTIndexGetPosition 




HTIndexGetProperty 

N otesDocument 

FTSearchScore 



NotesDocumentCollection 

IsSorted 


Continued 
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HiTest 

Class 

HiTest Functions 

LotusScript Notes Classes 

LotusScript Notes Classes: 

Properties and Methods 


HTIndexGetV iewPosition 




HTIndexN avigate 

N otesDocumentCollection 

GetLastDocument, GetNextDocument, 
GetPrevDocument, GetNextSibling, 
GetPrevSibling, GetChild, GetParent 


HTIndexOpen 

HTIndexOpenView 

HTIndexRefresh 

HTIndexSearch 

NotesDocumentCollection 

Refresh 


HTIndexSetPosition 

NotesDocumentCollection 

GetFirstDocument, GetNthDocument 



NotesDocumentCollection 

GetFirstDocument, GetNthDocument 


HTIndexSetProperty 




HTIndexSetViewPosition 

NotesDocumentCollection 

GetDocumentByKey 

Item 

HTItemAppendT extList 

N otesDocument 

AppendToTextList 


HTItemCopy 

N otesDocument 

Copyltem 



Notesitem 

CopyltemT oDocument 


HTItemDelete 

Notesitem 

Removeltem 


HTItemDelete 

Notesitem 

Remove 


HTItemFetch 

Notesitem 

GetItemValue, Hasitem, GetItemValue, 
Signer, IsSigned, Authors 



Notesitem 

Values, DateTimeValue 


HTItemGetCount 




HTItemGetInfo 




HTItemGetLength 




HTItemList 

Notesitem 

GetFirstItem, GetNextItem, Items 



Notesitem 

Name, ValueLength, Type, IsNames, 
IsReaders, IsAuthors, IsSigned, 
IsEncrypted, IsSummary, IsProtected 


HTItemPut 

Notesitem 

Replaceltem, AppendItemValue, Sign, 
PutInFolder, RemoveFromFolder 



Notesitem 

New 



Notesitem 

Contains 



Notesitem 

Abstract 


Continued 
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HiTest 

Class 

HiTest Functions 

LotusScript Notes Classes 

LotusScript Notes Classes: 

Properties and Methods 

Mail 

HTMailCreate 

N otesDocument 

CreateReplyMessage, 

SaveMessageOnSend, 


HTMailSend 

NotesDocument 

Send 

Server 

HTServerExecute 




HTServerGetProperty 




HTServerList 




HTServerReplicate 




HTServerSetPort 



Session 

HTConvert 

HTConvertGetLength 

HTGetAPILibraryVersion 

HTGetEnvironmentString 

HTGetEormat 

HTGetInternational 

NotesSession 

GetEnvironmentString 


HTGetProperty 

NotesSession 

UserName, CommonUserName, 
IsOnServer, NotesVersion 


HTInit 

NotesSession 

New 


HTSetEnvironmentString 

NotesSession 

SetEnvironmentV ar 


HTSetEormat 

HTSetInternational 

HTSetProperty 

HTStringEetch 

HTTerm 

HTTranslate 

NotesSession 

Close 

TextList 

HTTextListFetch 




HTTextListGetCount 




HTTextListGetLength 




Continued 
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HiTest 

Class 

HiTest Functions 

LotusScript Notes Classes 

LotusScript Notes Classes: 

Properties and Methods 

User 

HTUserRegisterCertifier 

HTUserRegisterServer 

HTUserRegisterWorkstation 

HTUserSetCertifier 



View 

HTViewCopy 




HTViewDelete 

NotesView 

Remove 


HTViewFetch 

NotesView 

Name 


HTViewList 




HTViewLocateByName 

NotesDatabase 

GetView 

Viewcell 

HTViewcellFetch 

NotesView 

Columns 


HTViewcellGetLength 
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Appendix B 
Special Notices 


This publication is intended to help Visual Basic programmers get 
acquainted with LotusScript to enable them to migrate their HiTest 
applications. The information in this publication is not intended as the 
specification of any programming inferfaces fhaf are provided by Lofus 
Nofes. 

References in fhis publicafion fo IBM producfs, programs or services do nof 
imply fhaf IBM infends fo make fhese available in all counfries in which 
IBM operafes. Any reference fo an IBM producf, program, or service is nof 
infended fo sfafe or imply fhaf only IBM's producf, program, or service 
may be used. Any funcfionally equivalenf program fhaf does nof infringe 
any of IBM's infellecfual properfy righfs may be used insfead of fhe IBM 
producf, program or service. 

Informafion in fhis book was developed in conjuncfion wifh use of fhe 
equipmenf specified, and is limifed in applicafion fo fhose specific 
hardware and software producfs and levels. 

IBM may have pafenfs or pending pafenf applicafions covering subjecf 
matter in fhis documenf. The furnishing of fhis documenf does nof give you 
any license fo fhese pafenfs. You can send license inquiries, in wrifing, fo 
fhe IBM Direcfor of Licensing, IBM Corporafion, 500 Columbus Avenue, 
Thornwood, NY 10594 USA. 

The informafion confained in fhis documenf has nof been submiffed fo any 
formal IBM fesf and is disfribufed AS IS. The informafion abouf non-IBM 
("vendor") producfs in fhis manual has been supplied by fhe vendor and 
IBM assumes no responsibilify for ifs accuracy or complefeness. The use of 
fhis informafion or fhe implemenfafion of any of fhese fechniques is a 
cusfomer responsibilify and depends on fhe cusfomer's abilify fo evaluafe 
and infegrafe fhem info fhe cusfomer's operafional environmenf. While 
each ifem may have been reviewed by IBM for accuracy in a specific 
sifuafion, fhere is no guaranfee fhaf fhe same or similar resulfs will be 
obfained elsewhere. Customers affempfing fo adapf fhese fechniques fo 
fheir own environmenfs do so af fheir own risk. 

Any performance dafa confained in fhis documenf was defermined in a 
confrolled environmenf, and fherefore, fhe resulfs fhaf may be obfained in 
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other operating environments may vary significantly. Users of fhis 
documenf should verify fhe applicable dafa for fheir specific environmenf. 

Reference fo RTF numbers fhaf have nof been released fhrough fhe normal 
disfribufion process does nof imply general availabilify. The purpose of 
including fhese reference numbers is fo alerf IBM cusfomers fo specific 
informafion relafive fo fhe implemenfafion of fhe PTF when if becomes 
available fo each cusfomer according fo fhe normal IBM PTF disfribufion 
process. 

The following ferms are frademarks of fhe Infernafional Business Machines 
Corporafion in fhe Unifed Sfafes and/or ofher counfries: 

IBM 

The following ferms are frademarks of ofher companies: 

C-bus is a frademark of Corollary, Inc. 

PC Direcf is a frademark of Ziff Communicafions Company and is used by 
IBM Corporafion under license. 

UNIX is a regisfered frademark in fhe Unifed Sfafes and ofher counfries 
licensed exclusively fhrough X/Open Company Limifed. 

Microsoff, Windows, and fhe Windows 95 logo are frademarks or 
regisfered frademarks of Microsoff Corporafion. 

Ofher frademarks are frademarks of fheir respecfive companies. 


The following are frademarks of Lofus Developmenf Corporafion in fhe 
Unifed Sfafes and/or ofher counfries. 


DafaLens 

InferNofes 

InferNofes Web Publisher 
Lofus 

Lofus Nofes Reporfer 
Lofus Nofes 
Lofus Nofes ViP 
Lofus @SQL 
LofusScripf 
Nofes 

Nofes HiTesf 


Nofes ViP 
Nofes Mail 
NofesPump 
NofesSQL 
Nofes/FX 
Phone Nofes 

Phone Nofes Mobile Mail 
Smarflcons 
Video Nofes 
Word Pro 
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Appendix C 
Related Publications 


The publications listed in this section are considered particularly suitable 
for a more detailed discussion of fhe topics covered in fhis redbook. 


International Technical Support Organization Publications 

For informafion on ordering fhese ITSO publicafions see "How To Gef ITSO 
Redbooks". 

• Developing Applications with Lotus Notes Release 4, SG24-4618, Lofus Parf 
No. 12394 

A complefe lisf of infernafional Technical Supporf Organizafion 
publicafions, known as redbooks, wifh a brief descripfion of each, may be 
found in: 

International Technical Support Organization Bibliography of Redbooks, 
GG24-3070. 
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How To Get ITSO Redbooks 


This section explains how both customers and IBM employees can find out 
about ITSO redbooks, CD-ROMs, workshops, and residencies. A form for 
ordering books and CD-ROMs is also provided. 

This informafion was currenf af fhe fime of publicafion, buf is continually 
subjecf fo change. The lafesf informafion may be found af URL 
hffp://www.redbooks.ibm.com/redbooks. 


How IBM Employees Can Get ITSO Redbooks 

Employees may requesf ITSO deliverables (redbooks, BookManager 
BOOKS, and CD-ROMs) and informafion abouf redbooks, workshops, and 
residencies in fhe following ways: 

• PUBORDER - fo order hardcopies in fhe Unifed Sfafes. 

• GOPHER link fo fhe Infernef - type gopher.wtscpok.itso.ibm.com. 

• Tools disks 

To get LIST3820s of redbooks, type one of fhe following commands: 
fools sendfo ehone4 fools2 redprinf gef sg24xxxx package 

fools sendfo canvm2 fools redprinf gef sg24xxxx package (Canadian 
users only) 

Note The currenf redbook LotusScript for Visual Basic Programmers is nof 
available as a LIST3820 or in BookManager formal. 

To gef lisfs of redbooks: 

fools sendfo wfscpok fools redbooks gef redbooks cafalog 

fools sendfo usdisf mkffools mkffools gef ifsocaf fxf 

fools sendfo usdisf mkffools mkffools gef lisfserv package 

To regisfer for informafion on workshops, residencies, and redbooks: 

fools sendfo wfscpok fools zdisk gef ifsoregi 1996 

Eor a lisf of producf area specialisfs in fhe ITSO: 

fools sendfo wfscpok fools zdisk gef orgcard package 

• Redbooks Home Page on fhe World Wide Web 
hffp:/ / w3.ifso.ibm.com/redbooks / redboooks.hfml 
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Note The current redbook LotusScript for Visual Basic Programmers is also 
available in HTML format and in Adobe Acrobat format on the World 
Wide Web. The URL is http://www.lotus.com/devtools. In addition, the 
code samples provided throughout the book are available for your use on 
hffp://www.lofus.com/redbook. 

• IBM Direcf Publicafions Cafalog on fhe World Wide Web 
hffp: / / www.elink.ibmlink.ibm.com / pbl / pbl 

IBM employees may obfain LlST3820s of redbooks from fhis page. 

• 1TS04USA cafegory on INEWS 

• Online - send orders fo: US1B6FPL af IBMMAIL or DKIBMBSH af 
IBMMAIL. 

• Infernef Lisfserver 

Wifh an Infemef e-mail address, anyone can subscribe fo an IBM 
Announcemenf Lisfserver. To inifiafe fhe service, send an e-mail nofe fo 
announce@websfer.ibmlink.ibm.com wifh fhe ke 5 rword subscribe in fhe 
body of fhe nofe (leave fhe subjecf line blank). A cafegory form and 
defailed insfrucfions will be senf fo you. 
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How Customers Can Get ITSO Redbooks 


Customers may request ITSO deliverables (redbooks, BookManager BOOKs, and CD-ROMs) 
and information about redbooks, workshops, and residencies in the following ways: 












Online Orders (Do nof send credif card informafion over fhe Infernef) — send orders fo: 

IBM Mail Internet 

usib6fpl at ibmmail usib6fpl@ibmmail.com 

caibmbkz at ibmmail lmannix@vnet.ibm.com 

bookshop at dkibmbsh at ibmmail bookshop@dk.ibm.com 


In United States 
In Canada: 

Outside North America: 


Telephone orders 

United States (toll free) 1-800-879-2755 

Canada (toll free) 1-800-IBM-4YOU 


Outside North America 
(+45) 4810-1320 - Danish 
(+45) 4810-1420 - Dutch 
(+45) 4810-1540 - English 
(+45) 4810-1670 - Finnish 
(+45) 4810-1220 - French 


(long distance charges apply) 
(+45) 4810-1020 - German 
(+45) 4810-1620 - Italian 
(+45) 4810-1270 - Norwegian 
(+45) 4810-1120 - Spanish 
(+45) 4810-1170 - Swedish 


Mail Orders - send orders to: 

IBM Publications IBM Publications 

Publications Customer Support 144-4th Avenue, S.W. 

P.O. Box 29554 Calgary, Alberta T2P 3N5 

Raleigh, NC 27626-0570 Canada 


Fax - send orders to: 
United States (toll free) 
Canada (toll free) 
Outside North America 


1-800-445-9269 

1-800-267-4455 

(+45) 48 14 2207 (long distance charge) 


IBM Direct Services 
Sortemosevej 21 
DK-3450 Allerod 
Denmark 


1-800-IBM-4FAX (United States) or (+1) 415 855 43 29 (Outside USA) — ask for: 

Index #4421 Abstracts of new redbooks 

Index #4422 IBM redbooks 

Index #4420 Redbooks for last six months 


• Direct Services — send note to softwareshop@vnet.ibm.com 

• On the World Wide Web 

Redbooks Home Page http://ww.redbooks.ibm.com/redbooks 

IBM Direct Publications Catalog http: / /www.elink.ibmlink.ibm.com/pbl/pbl 

The current redbook LotusScript for Visual Basic Programmers is also available in HTML format and in 

Adobe Acrobat format on the World Wide Web. The URL is http://www.lotus.com/devtools. In 

addition, the code samples provided throughout the book are available for your use on 

http://www.lotus.com/redbook. 

• Internet Listserver 

With an Internet e-mail address, anyone can subscribe to an IBM Announcement Listserver. To 
initiate the service send an e-mail note to annouce@webster.ibmlink.ibm.com with the keyword 
subscribe in the body of the note (leave the subject line blank). 
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c 

CDRecord, 162 
classes in LotusScript, 19, 21 
Close method, 120 
closing a database, 128,131 
collections, 8 

comparing HiTest and LotusScript, 
203 

comparing LotusScript and Visual 
Basic, 1 

compilation process, 39 
compile errors, 95 
composites, 162 
conditional compilation, 12 
constants, LotusScript and Visual 
Basic, 12,13 
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control arrays, 29 
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converting HiTest applications, 99 
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158 

creating a form, 172 
creating a view, 189 
creating embedded objects, 171,178 
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creating Notes objects in LotusScript, 
107 

cross-platform, 12 


D 

data types, LotusScript and Visual 
Basic, 5 

database classes, 45, 46, 47 
Datatype variable in LotusScript, 10 
DBCS, 7 
debugger, 40, 43 
declaring Notes classes in 
LotusScript, 90,109 
declaring Notes classes in Visual 
Basic, 90 

declaring variables, 6 
defining default variables, 7 
deleting a view, 140 
deleting an item, 168 
design pane, 34 
document ID, 145 

E 

editing an object, 191,192 
embedded objects, creating, 171 
embedded objects, managing, 189 
embedding a new object, 175,182 
embedding an entire file, 174,178 
embedding part of a file, 171,181 
End statement, 10 
error checking, 40 
error groupings, 14 
error handling, 10,13, 95 
externally creatable objects, 86,105 

F 

fields, 161 

file I/O, in LotusScript and Visual 
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ForAll, 10 

Forall and Foreach statements, 104, 
130,142,169 
forms, 31 

formula language, 35 
forward reference, 18 
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handling errors, 95 
hierarchical relationship, 45, 46 
history of LotusScript, 2 
HiTest, comparing with LotusScript, 
203 

HiTest API initialization, 113 
HiTest applications, converting, 99 
HiTest conversion, 116,126,138,150, 
166 

HTInit, 113 
HTOID, 145 
HTTerm, 113 
HTUNID, 145 

I 

IDE, 31 

inheritance, 21 
Integrated Development 
Environment, 31 

L 

linked objects, creating, 171 
linked objects, managing, 189 
locating a view, 140 
locking files, 9 
logic errors, 97 
Lotus Components, 17 
LotusScript, accessing Notes 
databases, 130 
LotusScript, accessing Notes 
documents, 156 

LotusScript, accessing Notes fields, 
169 

LotusScript, accessing Notes sessions, 
120 

LotusScript, accessing Notes views, 
142 

LotusScript, comparing with HiTest, 
203 

LotusScript, comparing with Visual 
Basic, 1 

LotusScript, creating embedded 
objects, 178,184 

LotusScript, creating linked objects, 
184 

LotusScript, declaring Notes classes, 
90 

LotusScript, deleting embedded 
objects, 196 
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196 

LotusScript, editing embedded 
objects, 194 

LotusScript, editing linked objects, 
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LotusScript, history, 2 
LotusScript, using type constants, 94 
LotusScript browser, 36, 38 
LotusScript debugger, 40, 43 
LotusScript text constants, 39 
LotusScript variables, 39 
LSERR.LSS, 14 

M 

mail enabling, 26 
main design window, 32 
managing embedded objects, 189 
managing linked objects, 189 
members, 45 

MessageBox statement in LotusScript, 
13 

methods, 45 

N 

navigators, 31 

New method, 104,120,127,131,132, 
158,169 

Notes classes, declaring in 
LotusScript, 90 

Notes classes, declaring in Visual 
Basic, 90 

Notes databases, accessing, 123 
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